Low-code application development

Turn creating applications into a low-code and user-friendly experience by using the tools that Pega
Platform offers. With Pega Platform, you can deliver flexible applications that help your customers reach
business goals in dynamically changing scenarios, in an efficient way.

When you develop your application by using the digital solutions that Pega Platform provides, you can
approach your project delivery holistically and efficiently at the same time. Implement the following
techniques to achieve your results faster:

Planning flexible Microjourneys

When you design your application, focus on a goal that your customers want to achieve. In
dynamically changing circumstances, predicting a fixed path through a business process might be
difficult and lead to inefficient results. Pega Platform refers to a path that leads to a successful
resolution as a Microjourney, and supports creating flexible templates for Microjourneys that can
adjust to events that take place on the way. In App Studio, you can clearly visualize the main elements
of your Microjourney: the people that are involved in the process, the channels that provide
communication with your application, and the data that is required to meet the goal. Consequently,
you can think about flexible sets of actions that might be useful during the processing of your
Microjourney. Visualization of the essential parts of your business processes can include also non-
technical stakeholders in the planning process.

For more information, see Creating a Microjourney for customer success.

Adopting feature-driven development

Develop capabilities in the context of a feature to maintain functional requirements and project status
directly in your application. You associate features with elements of your application that you want to
develop, for example, a language pack. For enhanced project management and effort tracking
purposes, you can use features to estimate project costs and schedules before you start actual
development.

For more information, see Adopting feature-driven development.

Reusing build-on capabilities

Reuse the functionality that you inherit from built-on applications, so that you can focus your
development efforts on unique features and capabilities. For example, you can create an application
for banking operations, and then reuse parts of it in applications for reviewing mortgage requests and
loan requests. For those three applications, the basic process of collecting and validating information
that customers provide might be the same. As a result, you save time but also deliver flexible
applications that you can edit independently from each other if your business requirements change,
for example, when the process for reviewing loan requests needs additional elements.

For more information, see Adding built-on applications.

Engaging and communicating with stakeholders and team members

Communication is a crucial part of developing applications. Starting with application planning, App
Studio offers tools to visualize business processes so that stakeholders from outside IT can be involved
in designing a Microjourney – a path towards customer success. Apart from that, Pega Platform
supports the uninterrupted exchange of information for development team members, as well as for
users who process cases in your application. Enhance collaboration with shareable documents, spaces
that gather professionally connected users, and messages that users can post in a Pulse gadget.

For more information, see Creating a Microjourney for customer success and Collaborating on cases.

Getting started with low-code application development

Start building your applications in a user-friendly and seamless way by implementing low-code digital
solutions. Save time when you create your applications by using templates, develop various aspects of
your application by engaging collaborators with different skills and roles, and increase work efficiency
by configuring your application for reuse. To meet your unique needs, use the Pega Platform authoring
portals.

Understanding project roles and personas

 For the best user experience, define how users interact with your application by understanding what
roles and personas your project requires. When you know who uses your application, and how, you can
update the interactions to provide the most relevant content to users.

Creating a Microjourney for customer success

Help your customers reach a successful resolution in their business processes by applying the Pega
Express methodology while working on implementation projects through journeys and microjourneys.
When you focus on one journey at a time, you not only improve how you address the specific needs of
your customers, but also reach results more rapidly.

Designing applications for reuse and extension

Save time and speed up your application development process by designing your applications for
reuse and extension. When you create reusable elements, such as rules and classes, you can
implement them again in future projects, to make your work more efficient.

Building logic and calculating values in your application

Provide automations for calculating values and implementing logic so that your application can flexibly
respond to unique conditions at run time. For example, you can create a process of transforming data,
and, as a result, present users with relevant information when they perform work.

Configuring continuous integration and continuous deployment

Incorporate the effects of work of your development teams by implementing continuous integration
and deployment. Additionally, to speed application development and minimize the risk of conflicts, you
can provide separate sandboxes in which developers can work on multiple features simultaneously.

Engaging with stakeholders to define a Microjourney

To ensure that your Microjourney meets all customer needs, engage your stakeholders in the
application development process. When you clearly communicate with the other parties that are
engaged in your projects, you can fully understand the requirements of your clients, and then provide
effective solutions.

Troubleshooting tools and techniques

Maintain good quality and health of your application by using troubleshooting tools and techniques
that Pega Platform provides. You can view application metrics to locate any issues, and then fix them,
so that you deliver top quality application.

Case management
User experience

Getting started with low-code application development

Start building your applications in a user-friendly and seamless way by implementing low-code digital
solutions. Save time when you create your applications by using templates, develop various aspects of your
application by engaging collaborators with different skills and roles, and increase work efficiency by
configuring your application for reuse. To meet your unique needs, use the Pega Platform authoring portals.

Application development considerations

Before you start developing your application, consider the following factors:

Your business goal

In many situations, predicting an exact course of action for application development leads to fixed and
inefficient solutions. With Pega Platform, you can avoid that and instead create agile applications that
adjust to dynamically changing needs. center your application development around a goal that you
want to achieve to ensure that work can reach a successful resolution under any circumstances.
People in your business process
Determine what types of users need to access your application, and then define the content that is
appropriate for every user type. For example, a manager might need access more features than a
regular worker. Additionally, consider what communication channels, such as email or chat bot, your
 users might need, and what devices they use to process work.
Data in your business process
Every business case requires data to reach a resolution. Think about the information that you need to
collect from users, as well as the ways of gathering data. To save time, define how you can organize
and reuse data in your application. For example, instead of storing separate data objects for every
piece of personal information about a user, such as a name, surname, and phone number, you can
gather all this information in a personal details data object. Then, you can update or reference one
data object instead of multiple different instances.
Reusable elements
You can save considerable amounts of time and resources during application development by reusing
various assets. For example, if you already have an application to review loan requests, you can reuse
any relevant elements to develop an application for reviewing mortgage requests, or performing other
banking operations.

Authoring portals
Pega Platform offers multiple tools that you can use based on your experience, role, and level of expertise.
You can use the following authoring portals to develop your applications:

App Studio
Select this portal if you are a citizen developer, front-end developer, business analyst, or data
engineer. App Studio holds a great variety of low-code, time-saving solutions for you to implement
during your application development. With a real-time UI design, any person that is involved in a
business process can contribute to application planning and development.

For more information, see App Studio overview and Creating a Microjourney for customer success.

Dev Studio
Select this portal if you are an experienced application developer, a security administrator, or an
account administrator. Dev Studio offers tools for advanced application configuration, such as
versioning, rules management, or branched development.

For more information, see Dev Studio overview.

Admin Studio
Select this portal if you are a system administrator. In Admin Studio, you can monitor and manage
your system resources, such as nodes and background processes.

For more information, see Admin Studio overview.

Prediction Studio
Select this portal if you are a data scientist. In Prediction Studio, you can develop, monitor, and adjust
models for analyzing customer interactions and communications to predict their future behavior.

For more information, see Prediction Studio overview.

The following figure summarizes factors and authoring portals to consider before you start creating your
applications:

Pega Platform ecosystem

 Exploring application

To experience all the possibilities that Pega Platform provides, explore your application.

Building your first application

Create low-code applications in a user-friendly and intuitive way by working with Pega Platform. With
various out-of-the-box tools, you can define customer journeys, develop applications, track your
progress, and communicate with team members and stakeholders.

Basic requirements for deploying public-facing applications

To ensure the security and branding of your public-facing applications, review and follow the minimum
requirements for deployment through Pega Platform.

Case management
User experience
Data modeling
Understanding project roles and personas
Creating a Microjourney for customer success
Designing applications for reuse and extension
Engaging with stakeholders to define a Microjourney
Troubleshooting tools and techniques

Exploring application
To experience all the possibilities that Pega Platform provides, explore your application.

App Studio overview

Turn your application development into a no-code, user-friendly experience by working in App Studio.
In this authoring environment, you can configure the main elements of your applications that include
 templates for your business processes, personas that are involved in the processes, interaction
channels, and data.

Dev Studio overview

Configure advanced technical options for your applications in a low-code and goal-oriented way by
exploring the tools available in Dev Studio. You can use Dev Studio to save time by managing the
reusable resources in your application in a more detailed way, and to configure advanced settings for
applications that focus on complex or exceptional business cases.

Admin Studio overview

Monitor and manage resources in your system more efficiently by using the tools that Admin Studio
provides. You can use Admin Studio to access run-time information and configuration options for the
resources that you create in Dev Studio.

Prediction Studio overview

Prediction Studio is an authoring environment in which you can control the life cycle of AI and machine
learning models (such as model building, monitoring, and update). From Prediction Studio, you can
also manage additional resources, such as data sets, taxonomies, and sentiment lexicons.

Changing your workspace

For the complete and multidimensional development of your application, switch from one workspace
to another to change the tools and features that are available in your work environment. For example,
you can create resources such as job schedulers in Dev Studio, and then manage and monitor those
resources in Admin Studio.

Exploring application-editing mode

Explore application-editing mode to learn about the tools and information that support application
development.

App Studio overview

Turn your application development into a no-code, user-friendly experience by working in App Studio. In
this authoring environment, you can configure the main elements of your applications that include
templates for your business processes, personas that are involved in the processes, interaction channels,
and data.

App Studio purpose

App Studio provides you with tools to develop your applications in a way that is convenient and
understandable for a citizen developer with little or no knowledge of any programming language. In App
Studio, you can prepare the following application elements:

reusable templates for your business processes that Pega Platform refers to as case types, and that
users complete at run time to reach a successful outcome.
personas that you create to visualize groups of users that interact with your application, such as
customers, workers, or managers. You can define access settings for each group so that users view
and process only relevant information.
data objects to ensure that the users have information required to resolve cases.

The approach of building your business processes on case types, personas, and data objects is a part of the
Pega Express methodology, the method of delivering projects in a no-code and user-oriented way. In the
Pega Express methodology, you use App Studio to model your business processes by creating case types,
personas, and data objects. A single business process that results in an expected outcome is a
Microjourney.

App Studio roles

App Studio targets business analysts, citizen application developers, front-end developers, and data
engineers. For improved communication between developers and stakeholders, App Studio supports real-
time UI design, so that any person that is involved in a business process can contribute to application
planning and development, the approach that helps achieve the best effects while providing IT solutions for
business.

App Studio tools

In App Studio, you can find multiple tools for developing and maintaining applications. On the Overview
page, you can find basic information about your application, for example, case types and personas that
your application includes. By exploring work areas, you can quickly view and create the main parts of your
application, such as case types, personas, channels, and UI elements. Each work area offers no-code
solutions that you can use to model your business processes in the most efficient way. The following figure
shows what you can find in each work area:

Exploring App Studio

To see the results of your work at run time, preview an application display on a device, and launch portals
associated with your application. While in a preview, you can turn on the design mode to conveniently
make any necessary adjustments by interacting with UI elements. Apart from building applications, in App
Studio you can work with tools to collaborate with other developers and track your development work, for
example, by posting messages and toggling Agile Workbench. To ensure that you maintain a good health
and quality of your application, explore options that you can use to monitor and maintain your application
performance. The tools include Clipboard, Tracer, and Accessibility Inspector.

App Studio access

To access App Studio, you associate the pxExpress portal with your access group. For more information,
see Granting portal access to an access group.
From App Studio you can switch to another workspace any time and change the tools and features that are
available in your work environment. For more information, see Changing your workspace.

What to do next: Start planning and implementing your Microjourney. See Creating a Microjourney for
customer success

Creating a Microjourney for customer success

The Microjourney in the Pega Express methodology FAQ

Dev Studio overview

Configure advanced technical options for your applications in a low-code and goal-oriented way by
exploring the tools available in Dev Studio. You can use Dev Studio to save time by managing the reusable
resources in your application in a more detailed way, and to configure advanced settings for applications
that focus on complex or exceptional business cases.

Dev Studio purpose and roles

Dev Studio contains tools that you can use to develop advanced aspects of your application in a
convenient, low-code way. In many scenarios, Dev Studio expands the possibilities that App Studio offers,
so that you can create applications for unique, complex, and less common business processes. Dev Studio
combines access to all of the capabilities that you might need when you create an application, such as case
management, security, reporting, mobile, and UI, so that you can provide end-to-end digital solutions for
your projects.

The focus in Dev Studio is on advanced functionality, such as system settings and rules, with access to rule
forms and rules management. In Dev Studio, you can also manage security, versioning, and source control
of your application. Target Dev Studio users include experienced application developers, security
administrators, and account administrators.

Dev Studio tools

Dev Studio provides you with tools to first configure and than maintain your application. On the Home tab,
you can quickly view recent guardrail warnings to check the compliance as well as the security status of
your applications. By exploring the various work areas, you can access and manage the resources that your
application includes. For example, you can view, edit, and create the reusable templates of your business
processes that Pega Platform refers to as case types. The Data types work area helps you manage data for
your application. By creating data types and supplementing them with data pages, you ensure that users of
your application have the information they require to resolve business processes. In the App and Records
areas, you can find the elements that are the technical building blocks of your application – the rules,
classes, and branches. You can also quickly preview the results of your work at run time by launching a
portal that you associate with your application. As a result, you can create applications that precisely meet
your unique business needs.

Apart from building applications, Dev Studio provides you with tools for collaborating with other developers
and tracking your development work, for example, by posting Pulse messages and opening Agile
Workbench. To ensure that you maintain the good health and quality of your application, you can explore
different options for monitoring and maintaining your application performance with tools such as the
Clipboard, Tracer, and Accessibility Inspector.

The following figure explores some of the Dev Studio tools:

Exploring Dev Studio

Dev Studio access
To access Dev Studio, ensure that you associate the Developer portal with your access group. For more
information, see Granting portal access to an access group.

From Dev Studio you can switch to another workspace at any time and change the tools and features that
are available in your work environment. For more information, see Changing your workspace.

Admin Studio overview

Monitor and manage resources in your system more efficiently by using the tools that Admin Studio
provides. You can use Admin Studio to access run-time information and configuration options for the
resources that you create in Dev Studio.

Admin Studio purpose and roles

Admin Studio focuses on system administration and provides tools for monitoring and debugging resources
in your system. Target users of Admin Studio are system administrators.

Admin Studio tools

By exploring the work areas that Admin Studio includes, you can maintain the top performance of your
application. In the Overview work area, you can view data about your system and analyze information
about all of the resources available in your environment. For example, you can check how many nodes your
application includes in total, and how many of those nodes are currently running. The Resources work area
provides access to landing pages that focus on specific resources in your system. Depending on the
resource, apart from viewing a list of resource instances available in your system, you can also investigate
and fix issues, start and stop resources, or even remove resources from the system. In Admin Studio, you
can also configure the settings for a mobile build server and manage the cache for users of your
application's mobile channel, as well as preview system details, available nodes, other applications, and
Java classes.

The following figure explores some of the tools in Admin Studio:

Exploring Admin Studio

Admin Studio access

To access Admin Studio, ensure that you associate the pxAdminStudio portal with your access group. For
more information, see Granting portal access to an access group.

From Admin Studio you can switch to another workspace at any time and change the tools and features
that are available in your work environment. For more information, see Changing your workspace.

Managing system resources

Prediction Studio overview

Prediction Studio is an authoring environment in which you can control the life cycle of AI and machine
learning models (such as model building, monitoring, and update). From Prediction Studio, you can also
manage additional resources, such as data sets, taxonomies, and sentiment lexicons.

To access Prediction Studio, you must specify pxPredictionStudio as one of the portals associated with your
access group. From Prediction Studio, you can switch to another workspace any time and change the tools
and features that are available in your work environment. For more information, see Changing your
workspace.

The following components are available in Prediction Studio:

Prediction Studio Header

The header at the top of Prediction Studio enables you to view the name of the current application, perform
a search across the rules in that workspace, view the online help, and toggle the Agile Workbench.

Page header
The page header at the top displays the name of the current work area, for example Predictions and
enables you to perform a number of common actions such as viewing model reports, clearing deleted
models, and so on. This toolbar also allows you to add models or additional resources.

Navigation panel
The navigation panel on the left provides quick access to the following work areas:

Predictions
In this work area, you can create predictions by answering several questions about what you want to
predict. You can also access, manage, and run existing predictions withing your application.

For more information about predictions, see Creating and managing predictions.

Models
In this work area, you can access, sort, and manage predictive, adaptive, and text analytics models
within your application. By default, the models are displayed as tiles. Each model tile contains an icon
for quick identification of model type, the model name, and the indication of whether the model is
completed or being built.
Data
In this work area, you can create and manage data sets or Interaction History summaries. In addition,
you can access resources such as taxonomies or sentiment lexicons that provide features for building
machine learning models.
Settings
This work area contains the global settings for model development, such as the internal database
where model records and related resources are stored, their default application context, and model
transparency policy.

Overview of Prediction Studio workspace

Prediction Studio transitions
You can quickly transition between Prediction Studio and business portals such as Pega Customer Decision
Hub. When in Prediction Studio, you can click the Back widget to return to a business portal with no
context change.

Developing and managing models

Changing your workspace

For the complete and multidimensional development of your application, switch from one workspace to
another to change the tools and features that are available in your work environment. For example, you
can create resources such as job schedulers in Dev Studio, and then manage and monitor those resources
in Admin Studio.

1. In the header of your workspace, click the Switch Studio menu.

The label for this menu is the name of your current workspace.
2. Select the workspace in which you want to work.
You have access only to the workspaces that are relevant to your role. For more information, see
Granting portal access to an access group.
You have access only to the workspaces that are relevant to your role. For more information, contact
your security administrator.

Adding personas to organize users

Exploring application-editing mode

Explore application-editing mode to learn about the tools and information that support application
development.

Application-editing mode is enabled by default.

1. If you have turned off application-editing mode, turn it on.

a. In the footer of App Studio, click the Open runtime toolbar icon.
b. Click Turn editing on.
2. In the header of App Studio, click the Resources icon.
3. Click Take a tour.
4. Follow the prompts on the screen to discover the different tools that you can use to develop your
application.

What to do next: Leave application-editing mode on while you set up your environment.

Building your first application

Building your first application

Create low-code applications in a user-friendly and intuitive way by working with Pega Platform. With
various out-of-the-box tools, you can define customer journeys, develop applications, track your progress,
and communicate with team members and stakeholders.

To ensure that your application is secure, use the Application Security Checklist. For more information, see
Assessing your application using the Security Checklist.

Start building your application by performing the following tasks:

Creating applications

Start developing your projects conveniently and intuitively by building your application on an
application template. When you create an application on a template, you save time because you reuse
key elements of an existing application, such as case types or data types.

Inviting collaborators to your application

Enhance your application and begin processing your business cases by inviting collaborators with
different skills and roles.

Setting your application password

Improve the security of your application by setting a password. When you define a password, you
ensure that only appropriate users can manage updates in your application.

Configuring applications for reuse

To save time and immediately start application development, make your application available as a
template. When you save your application as a template, other users can quickly build a new
application from that sample. The newly created application automatically inherits template logic,
data, and personas.

Configuring advanced settings for new applications

To fully benefit from possibilities Pega layer cake provides, configure advanced settings for your
application and create organization layers. To save time, reuse common processes within your
organization, and to adjust the application to your departmental business needs, allow for greater
customization of certain elements.

Switching between applications

When you work on multiple applications, you can switch between them by using the My Applications
gadget.

Adding built-on applications

To save time and reduce development costs you can reuse elements between your applications, such
as rules and features, by adding built-on applications. When you build your application stack, you
ensure that you meet business requirements in an efficient way.

Automating work by creating case types

User experience

Creating applications
Start developing your projects conveniently and intuitively by building your application on an application
template. When you create an application on a template, you save time because you reuse key elements of
an existing application, such as case types or data types.

You can choose a default application that Pega Platform provides, or create custom templates.
Before you begin: If you plan to use a custom application template, configure the template for reuse. For
more information, see Configuring applications for reuse. If you plan to collaborate with users without an
operator ID, configure the Default email account. For more information, see Creating an email account in
Dev Studio.Note: If you build your application on a custom template, fields to complete and the creation
process might vary.

1. In the header of Dev Studio, click the name of the application, and then click New Application.
 2. Choose a type of application to create:
To use the Pega Cosmos design system as a basis for your interface, click Cosmos.
To build directly on Pega Platform, click Classic.
To build your application on an application template, hover over the application name, and then
click Learn more.

For more information, see the implementation guide for your application.

To search for an application template, click Search all types.

3. Click Use this application type.
4. If you build your application on a custom template, and you want to reuse resources from the
application, such as case types or data types, import the resources to your new application:
a. In the Select case types section, select the check box next to each relevant case type.
b. Click Continue.
c. In the Select data types section, select the check box next to each relevant data type.
d. Click Continue.
5. In the Name your application field, enter a unique name for your application.
6. Optional: To configure a custom class structure or organization, click Advanced configuration.
For more information about the settings that you can change, see Configuring advanced settings for
new applications.
7. Click Create application.
8. Optional: To develop your application more quickly, in the Optionally, add users section, create a
team:
a. In the text field, press the Down arrow key, and then select a user name or an email address.
If you enter an email address that is new in the system, the system creates a new user.
b. Control which type of access the user has to your application by selecting a role in the list.
c. Click Add.

Caution: If an email account error occurs when you add a user, take note of the user ID and
generated password, because the user may not receive these credentials in an email.

9. Click Go to app.

Styling your application with design systems

Configuring applications for reuse
App Studio overview

Inviting collaborators to your application

Enhance your application and begin processing your business cases by inviting collaborators with different
skills and roles.

For example, you can invite members of a development team so that the team can start working on
building your application. When you invite collaborators, you associate them with personas that you create
in your application. Personas define type of access that you grant to the users of your application.
Before you begin: Define types of access for the users of your application. See Granting personas access
to channels and pages.

1. In the navigation pane of App Studio, click Users, and then click People.
2. In the working area, click Invite people to your application.
3. In the Add users to application window, in the autocomplete field, press the Down arrow key, and
then select a user name or email address. Result: If you enter an email address that does not exist,
the system creates a new user for you.
4. In the list, define a type of access that the user has to your application by selecting a role.
When you select a role, you associate a user with a persona. For more information about personas,
see Creating personas.
5. Click Add.
6. Send an email with an invitation to the user by clicking Send invitation.
7. Close the Add users to application dialog box.

What to do next: Analyze what data your case requires to reach a resolution by defining data objects. See
Adding data objects to organize data.

Creating a team
Creating applications
 Managing work across your team

Setting your application password

Improve the security of your application by setting a password. When you define a password, you ensure
that only appropriate users can manage updates in your application.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. On the Application form, click the Integration & security tab.
3. In the Application security section, select the Require password to update application check
box.
4. Click Update password.
5. In the Enter password and Confirm password fields, enter your password.
6. Click Submit.
7. Click Save.

Result: At run time, before users can save their changes, they provide a password.

Viewing test coverage reports

Configuring applications for reuse

To save time and immediately start application development, make your application available as a
template. When you save your application as a template, other users can quickly build a new application
from that sample. The newly created application automatically inherits template logic, data, and personas.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. On the Application wizard tab, select the Show this application in the New Application wizard
check box.
3. In the New Application wizard settings section, in the Short description field, provide the name
and purpose of your application:
To reuse existing information, press the Down arrow key, and then select a field value that stores
the information that you need.
To use a new name, enter a unique and descriptive label, for example, Hiring process.
4. In the Application description field, provide a description so that users can decide whether to reuse
your application:
To reuse existing information, press the Down arrow key, and then select a field value that stores
the information that you need.
To use a new description, enter a unique and descriptive text, for example, Use this application to process
job applications.
5. In the New application access list, select the access group that users receive when they reuse your
application.
You can only choose from development access groups, which are access groups that contain the
developer or pxExpress portals.
6. Optional: To distinguish your application when users select reusable templates, replace the default
logo and preview images:
a. In the Brand section, click Upload Image.
b. In the explorer dialog box, navigate to the file for your company or organization logo, and then
click Upload Image.
c. In the Desktop snapshot section, click Upload Image.
d. Navigate to a screen capture that is at least 370 pixels by 233 pixels, and then click Upload
Image.
e. In the Mobile snapshot section, click Upload Image.
f. Navigate to a screen capture that is at least 110 pixels by 194 pixels, and then click Upload
Image.
7. Click Save.

Result: When users run the new application wizard to create an application, they can choose your
application as a template and reuse its logic, data, and personas.

Creating applications
Creating a Microjourney for customer success
Adding built-on applications
Configuring advanced settings for new applications
To fully benefit from possibilities Pega layer cake provides, configure advanced settings for your application
and create organization layers. To save time, reuse common processes within your organization, and to
adjust the application to your departmental business needs, allow for greater customization of certain
elements.

You can create division and unit layers in your application to customize different layers. For example, if
your organization includes a Human Resources division and an Engineering division, configure your
application to reuse common processes between the divisions, and change elements that are different for
each division. For instance, reuse a process for calculating expenses, and specify different maximum
amounts for each division.

Before you begin: Create your application. For more information, see Creating applications.

1. In the Application structure section, select a structure for your application:

To create a generic application that you can reuse or extend later, select Framework.
To create a specialized application for a specific business audience, select Implementation.
2. In the Application ID field, enter an identifier for the application, for example, HiringApp.
An identifier starts with a letter, and contains only letters, numbers, and hyphens. If you set an
application name, the system generates an identifier based on the name.
3. In the Version field, enter a number that identifies the version of this application record, for example,
01.01.01 .
4. In the Organization settings section, in the Organization name field, specify an organization that
owns the application:
To reuse an existing organization, press the Down arrow key, and then select an organization.
To create an organization, enter a unique and descriptive name, for example, HROrg.
The default value is an organization of the user that creates the application.
5. In the Division name field, specify a division that owns the application:
To reuse an existing division, press the Down arrow key, and then select a division.
To create a new division, enter a unique name.
6. In the Unit field, specify a unit in the division:
To reuse an existing unit, press the Down arrow key, and then select a unit.
To create a new unit, enter a descriptive name.
7. In the Class layers section, configure the class structure of your application:
a. Optional: To create a new division layer, select the Generate division layer check box, and
then, in the Division field, specify a name of the division from the new layer.
b. Optional: To create a new class layer, select the Generate class layer check box, and then, in
the Class field, specify the class for the new layer.
c. If you create a new organization, in the Organization field, enter the organization name.
This option is read-only when you choose an organization that already exists.
8. In the Application field, enter a value that defines the application class layer for the application stack.
If you leave this field blank, the application uses the value that you provide in the Application ID
field.
9. In the Class group name field, enter a name that an application uses to create work queues for
users.
The default value is Work.
10. Click Save.

Creating a rule
Organizing rules

Switching between applications

When you work on multiple applications, you can switch between them by using the My Applications
gadget.

By default, the My Applications gadget is available in App Studio.

Before you begin: To switch between applications in portals other than App Studio, add the gadget. For
more information, see Adding the My Applications gadget.

1. In the header of App Studio, click My Applications.

2. From the list, select an application that you want to open.
3. Optional: If you have more than one access role in the application, select the role that you want to
 use, and then click Go.

Adding the My Applications gadget

To conveniently navigate between your applications, add the My Applications gadget to your existing
portal or application by embedding a header and a menu.

Changing your workspace

Adding the My Applications gadget

To conveniently navigate between your applications, add the My Applications gadget to your existing portal
or application by embedding a header and a menu.

By using the My Applications gadget, you can see an overview of your applications with short descriptions,
customize the icons of your applications, and search the applications by name. By default, the My
Applications gadget is available in App Studio.
Before you begin: Ensure that your application uses UI Kit 14 or any of its later versions.

1. In Dev Studio, open an application in which you want to add the My Applications gadget.
For more information, see Switching between applications.
2. In the navigation panel, click Records User Interface Section , and then open the pyPortalHeader
section.
3. Right-click the embedded pyAppLauncher section, and then click Copy.
4. Open the section where you want to add the My Applications gadget.
5. Right-click the section, and then click Paste.
6. Open the pyPortalHeader section.
7. Repeat steps 3 through 5 for the My Applications icon.
8. Click Save.

Harness and section forms - Adding a section

Adding built-on applications

To save time and reduce development costs you can reuse elements between your applications, such as
rules and features, by adding built-on applications. When you build your application stack, you ensure that
you meet business requirements in an efficient way.

For example, when you create an application to review mortgage requests, you can add a built-on
application that workers use to review loan requests, and then reuse the elements that are relevant to the
mortgage cases.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. In the Built on applications section, click Add application.
3. In the Name field, enter the name of the application that you want to add.
4. In the Version field, enter the version of the application that you want to add.
As a best practice, add the latest version of your application.
5. To add more built-on applications, repeat steps 2 through 4.
6. Click Save.

Result: When you work on your current application, you can reuse resources from your built-on
applications.

Best practices for using multiple built-on applications

To increase reuse between your Pega Platform applications and speed up the development process,
enhance your applications by using multiple built-on applications. Built-on applications are structured
as a hierarchical application tree.

Application stack hierarchy for multiple built-on applications

When you use multiple built-on applications, Pega Platform automatically converts the hierarchical
application tree of multiple built-on applications into a single linear application stack. As a result, you
can shorten development time and increase consistency in your application by reusing rulesets and
frameworks.
 Designing applications for reuse and extension
Organizing rules
Managing relevant records and components
Adopting feature-driven development

Best practices for using multiple built-on applications

To increase reuse between your Pega Platform applications and speed up the development process,
enhance your applications by using multiple built-on applications. Built-on applications are structured as a
hierarchical application tree.

By using multiple built-on applications, you break up common and stand-alone components into their own
applications, and provide the ability to point an application to another application rule, helping to
automatically update any required rulesets and versions across applications when applications undergo
changes.

For example, the uPlus organization creates an application layer to contain the definition of common assets
and integrations in corporate systems. Separating each integration into its own built-on application can
simplify the revisioning of each integration by removing dependencies. As a result, applications use
features independently and when developers want to upgrade a feature, they can upgrade only a specific
built-on application, without affecting the others.

Best practices for using multiple built-on applications

Consider the following tips when developing an application that uses multiple built-on applications:

Limit development to rulesets in the top-most application and keep built-on applications locked.
To develop in the lower layers of the hierarchical application tree, switch to a built-on application
layer.
Avoid having the same ruleset in multiple applications. Instead, refactor the ruleset to its own
application or a common application.
Avoid using different versions of an application in the hierarchical application tree.
Avoid branch IDs that span several applications.
Avoid making any application structure changes without utilizing the Validation Tool to validate rules.
Avoid using Ruleset Validation mode rulesets. Ruleset prerequisites can be challenging to maintain,
especially when you need to refactor the application stack. Always default to using Application
Validation mode rulesets, which create the ruleset stack depending on the application in which you
define the rulesets.

Application stack hierarchy for multiple built-on applications

Adding built-on applications
Validation tool
Configuring ruleset version settings

Application stack hierarchy for multiple built-on applications

When you use multiple built-on applications, Pega Platform automatically converts the hierarchical
application tree of multiple built-on applications into a single linear application stack. As a result, you can
shorten development time and increase consistency in your application by reusing rulesets and
frameworks.

Pega Platform creates the linear application stack using the following rules:

The system always locates PegaRULES at the end of the linear application stack list.
Pega Platform processes each built-on application by using a depth-first algorithm that searches as far
as possible along an application tree branch before moving on to another branch.

An application tree branch consists of a built-on application and its built-on applications.

For duplicate applications with the same application version, Pega Platform retains only the application
that has the lowest position in the tree in the application stack list, and ignores the other application.
For duplicate applications with different application versions, as well as for PegaRULES, Pega Platform
uses the numerically highest available application version.
The following image represents the automatic conversion of a hierarchical application tree into a single
linear application stack at run time:

Automatic conversion into a single linear application stack

Ruleset behavior at design time

Each application in the hierarchical application tree consists of various rulesets that Pega Platform
automatically assembles into a linear ruleset stack. This ruleset stack defines which rulesets a specific rule
can use for context purposes at design time.

Ruleset stack assembly generally follows the same guidelines as for creating the linear application stack at
run time. However, ruleset stack assembly for a specific rule is based on the specific application that the
rule belongs to, which is also called the rule's owning application.

After Pega Platform determines a rule's owning application, Pega Platform automatically creates the linear
ruleset stack for that specific rule, starting with the rule's owning application and working through the
hierarchical application tree branch to PegaRULES.

Note: The behavior described above applies only when you save a rule in an Application Validation mode
ruleset. When saving a rule in a Ruleset Validation mode ruleset, you must specify prerequisites in the
REQUIRED RULESETS AND VERSIONS section on the Versions tab of the ruleset.

When you use Application Validation mode, at design time, the saved rule cannot reference certain rulesets
that are available at run time. This restriction allows for the appropriate isolation of applications, and makes
applications easier to reuse.

Example of the transition from hierarchical to linear ruleset

stack assembly
In the following example, the hierarchical application tree contains only rulesets that use the Application
Validation mode:
MortPlus 01.01 (Ruleset1

Underwriting 01.01 (Ruleset2) Pricing 01.01 (Ruleset4)

uPlusFin 01.02 (Ruleset3) uPlusFin 01.01 (Ruleset5)

PegaRULES PegaRULES
If you save RuleABC in Ruleset2, the Underwriting application becomes the rule's owning application. Pega
Platform then assembles the ruleset stack that RuleABC can use at design time according to the following
pattern:
Ruleset2 Ruleset3 PegaRULES

Pega Platform starts building the ruleset stack at the Underwriting application, and then processes the
stack through PegaRULES in that specific application tree branch. Because the Pricing application is located
on a separate application tree branch, at design time, ruleset stack processing cannot reference Ruleset4
and Ruleset5 from the other tree branch.

Ruleset behavior at run time

At run time, Pega Platform creates the linear application stack for the entire tree of built-on applications by
following the preceding guidelines. This application stack is the basis for application functionality in a live
environment.

Use case examples

The following use cases describe how Pega Platform processes the hierarchical application tree into a single
linear application stack at run time.

Note: These examples are for demonstration purposes only and might not represent the application
structure of current application offerings.
For example:

Use case 1: Multiple applications that use the same PegaRULES

version
In this example, the TopApp application is built on the BaseApp1, BaseApp2, and BaseApp3 applications. All
applications are built on the same version of PegaRULES.

TopApp [Ruleset1

BaseApp1 BaseApp2 BaseApp3

PegaRULES

The resulting application stack has the following structure:

TopApp BaseApp1 BaseApp2 BaseApp3 PegaRULES

The system processes each built-on application by using a depth-first algorithm.

For example:

​Use case 2: Multiple applications that use different PegaRULES

versions
In this example, the MyCustomerApp application is built on the BillingApp and SupportApp applications.
Each of these applications is built on a different version of PegaRULES.

MyCustomerApp (Ruleset1

BillingApp (Ruleset2) SupportApp (Ruleset4)

BillingPlansApp (Ruleset3) PegaRULES 07.05

PegaRULES 07.01

The resulting application stack has the following structure:

MyCustomerApp BillingApp > BillingPlansApp SupportApp PegaRULES:07.05

Pega Platform uses version of PegaRULES with the highest available number in the application stack list.
For example:

Use case 3: A duplicated application with different versions

In this example, the ProductionApp application is built on the FinalAppTemplate application, which is built
on the CustomerApp and EmployeeApp applications. Each of these applications has additional built-on
applications, including the duplicated MyBusinessApp application, which has two different versions in use.
All applications are built on the same version of PegaRULES.

ProductionApp 01.01 (Ruleset1

FinalAppTemplate 01.01 (Ruleset2

CustomerApp 07.01 (Ruleset3) EmployeeApp 01.01 (Ruleset6)

ServicesApp 01.01 (Ruleset4) MyBusinessApp 01.01 (Ruleset7)

MyBusinessApp 01.02 (Ruleset5) PegaRULES 07.01

PegaRULES 07.01

The resulting application stack has the following structure:

ProductionApp FinalAppTemplate CustomerApp ServicesApp EmployeeApp MyBusinessApp:01-

02 PegaRULES

Even though the system retains the application with the lowest position in the tree list, the application
stack list uses the numerically highest available version for the duplicated application.

For example:

Use case 4: A duplicated application with multiple branch

points
In this example, the MyCustomApp application is built on several other applications, including two
applications that both contain the same MyHealthApp application. All applications are built on the same
version of PegaRULES.

MyCustomApp

ComplexApp BasicApp1 BasicApp2

MyPlanner ResultsApp SurveyApp PegaRULES

MyReports MyHealthApp ​PegaRULES

MyHealthApp PegaRULES

PegaRULES

MyCustomApp has four built-on applications: ComplexApp, BasicApp1, BasicApp2, and PegaRULES. The
resulting application stack has the following structure:

MyCustomApp ComplexApp MyPlanner MyReports BasicApp1 ResultsApp MyHealthApp

BasicApp2 SurveyApp PegaRULES

Duplicate applications with the same version use the lowest-positioned application in the tree list.

For example:

Use case 5: An application with branches

In this example, the MyCallCenter application has two branches: Branch_MyCallCenterRS and
Branch_Policies. All applications are built on the same version of PegaRULES.
 MyCallCenter

Branch_MyCallCenterRS
Branch_Processes

MyStaffingApp Processes

Policies PegaRULES

PegaRULES

The resulting application stack has the following structure:

MyCallCenter MyStaffingApp Policies Processes PegaRULES

Best practices for using multiple built-on applications

Adding built-on applications

Basic requirements for deploying public-facing applications

To ensure the security and branding of your public-facing applications, review and follow the minimum
requirements for deployment through Pega Platform.

Note: Do not deploy any public-facing applications that you develop in Pega Platform without following
these basic requirements. If you cannot complete an item on this list, immediately notify the application
owner of the security risks and of the omitted tasks.

The Security Checklist: Best practices for securely deploying

your application
Security is critical in all applications, especially in applications that are used by external operators, such as
customers and prospective customers, who are not your employees. Inadequate security might cause the
deployment of your application to fail.

To secure your application, complete the Security Checklist to:

Follow best practices for securely deploying applications.

Ensure the confidentiality, integrity, and availability of your application in production.
Identify when each task should be performed: at or near the beginning of development, on an ongoing
basis, or just before deployment.
Avoid expensive rework late in your development process.

Unless otherwise noted, these recommendations apply to all deployment environments, including Pega
Cloud services.

The most important security requirement for all applications is to maintain guardrail-compliance because
Pega Platform security features cannot always be successfully enforced in custom code. You can secure
applications by configuring only the built-in features in Pega Platform, without relying on custom code that
is built by developers who are not security experts.

For more information, seeSecurity Checklist.

Pega Platform shows the overall completion of the Security Checklist on the Dev Studio home page, and
provides tools to track the status of each task.

For more information, see Preparing your application for secure deployment.

Public users authentication

Unauthorized individuals should not have access to view or modify the application or its data. Always verify
the identity of application users, and apply one of the following types of Authentication Services, based on
the user type:
Anonymous user
A user is initially anonymous (identity unknown). The users may register themselves or have their
identity verified partway through a session.

For example, in online shopping, unauthenticated users can browse and add items to a shopping cart,
and then either create an account or enter their credentials to check out.

To configure authentication for applications that require anonymous users, you define the following
parameters:

An Authentication Service rule of the Anonymous type

An access group for all anonymous users
A limit for the access group to provide access to only data and applications functions that are not
in any way confidential (such as the product catalog and shopping cart)

After a user becomes a known user, either by registering or entering credentials, you can use the Re-
Authentication gadget to dynamically change their roles and privileges, so that the user can continue
their session without logging in again.

For more information, see Configuring an application to use an anonymous authentication service.

Authenticated user
User credentials must be verified during login through an external data store or database, such as a
customer master file.

User credentials are verified at the start of a session, but those credentials are stored outside of Pega
Platform.

To configure authentication for applications with authenticated users, you define the following
parameters:

An Authentication Service rule of the Basic Credentials type

The Verify credentials using an external identity store option
A data page for accessing an external data store

Single sign-on
Single sign-on (SSO) is a property of identity and authentication that enables users to securely
authenticate with a set of login credentials, such as a name and password. SSO is used and the
user is authenticated through their credentials on a social media site, such as Google.

For more information, see:

Configuring a basic authentication service

Creating a Google authentication service

Authentication in Pega Platform

Restrict access to data in Data-Admin-OperatorID class

In public-facing applications where end users do not need access to information about other operators, we
recommend that you restrict all access to data in the Data-Admin-OperatorID class to only the end user’s
data through an access control policy. You can do this by enabling the out-of-the-box rules pyDefault and
pyRestrictToSelf in the Data-Admin-OperatorID class.

If this rule does not exist in your Pega Platform release, you can create it in any release from 7.3 forward.
For more information, see Restricting access to operator information in public-facing applications in Pega
Platform 8.4 and earlier.

For more information, see:

Attribute-based access control

Creating an access control policy condition

Sensitive client data protection

Never deploy any application that creates or stores personally identifiable information (PII), such as social
security numbers, account numbers, health data, date of birth, addresses, phone numbers, or any other
sensitive data that could be used to identify an individual, without protecting that data from unauthorized
access.

To encrypt sensitive property values, apply these guidelines:

Set up a master key in an external Key Management System.

Define a Keystore rule instance that references the master key.
In Dev Studio, on the Data Encryption landing page, reference the Keystore rule that accesses the
master key.
Define PropertyEncrypt access control policies, and then list the properties to encrypt.
Define PropertyRead access control policies to conditionally mask or obfuscate these property values
for operators who should not be able to view them.

For more information, see:

Encrypting system data by using a custom key management service

Creating a keystore
Creating an access control policy

Branding and exposed information during user logins

Set up a descriptive and memorable (vanity) URL or custom domain name that does not unnecessarily
expose server information to users.

For more information about configuring the domain name on Pega Cloud, see Requesting a custom domain
name.

Restricting access to operator information in Pega 8.5

Restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data by using an
access control policy. You can restrict access to personally identifiable information (PII) for security
purposes, such as protection against unauthorized exposure of PII data. Restricting access to only the
end users' data increases the security and peace of mind of users who must communicate with clients
and customers through public-facing channels.

Restricting access to operator information in public-facing applications in Pega Platform 8.4 and earlier

Restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data by using an
access control policy. Enable this access to personally identifiable information (PII) for security
purposes, such as protection against unauthorized exposure of PII data. Restricting access to only end
users' data increases the security and peace of mind of users who must communicate with clients and
customers through public-facing channels.

Restricting access to operator information in Pega 8.5

Restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data by using an
access control policy. You can restrict access to personally identifiable information (PII) for security
purposes, such as protection against unauthorized exposure of PII data. Restricting access to only the end
users' data increases the security and peace of mind of users who must communicate with clients and
customers through public-facing channels.

To enable the pyDefault and pyRestrictToSelf rules in the Data-Admin-OperatorID class, follow the steps
below:

1. In the header of Dev Studio, click Create Security Access Control Policy Condition .
2. In the header of Dev Studio, click Records
3. Open the pyRestrictToSelf access control policy condition rule.
a. In the Policy Condition field, select pyRestrictToSelf.
b. In the Applies To field, select Data-Admin-Operator-ID.
4. Click Save As, then select the application ruleset for which you want to enforce this restriction, and
click Create and open.
5. On the rule form, click Availability, and then select Available from the list.
6. In the header of Dev Studio, click Records > Security > Access Policy Control .
 7. Open the pyDefault access control policy rule.
a. In the Policy name field, select pyDefault.
b. In the Action field, select Read.
c. In the Applies to field, enter Data-Admin-Operator-ID .
8. Click Save As, then select the application ruleset for which you want to enforce this restriction, and
click Create and open.
9. On the rule form, click Availability, and then select Available from the list.

Restricting access to operator information in public-facing applications in Pega Platform 8.4 and earlier
Configuring dynamic system settings
Access Control Policy rule

Restricting access to operator information in public-facing

applications in Pega Platform 8.4 and earlier
Restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data by using an
access control policy. Enable this access to personally identifiable information (PII) for security purposes,
such as protection against unauthorized exposure of PII data. Restricting access to only end users' data
increases the security and peace of mind of users who must communicate with clients and customers
through public-facing channels.

Before you begin:

enable this to restrict access to PII data for security purposes. It provides for hardening their application
against unauthorized exposure of PII data.

If you are using a version of Pega Platform earlier than 8.2, attribute-based access control (ABAC) is
disabled by default. To enable this feature, you need to create a dynamic system setting with the following
attributes:

1. In the header of Dev Studio, click Create SysAdmin Dynamic System Settings .
2. In the Short Description field, enter Enable Attribute BasedSecurity.
3. In the Owning Ruleset field, enter Pega-RulesEngine .
4. In the Setting purpose field, enter EnableAttributeBasedSecurity.
5. Click Create and Open.
6. On the Settings tab, in the Value field, enter True.

If your installation of Pega Platform does not contain the pyRestricttoSelf rule, from Pega Platform 7.3 and
later you can create it yourself.

1. In the header of Dev Studio, click Create Security Access Control Policy Condition .
2. Create an Access Control Policy Condition rule by clicking Create > Security > Access Control
Policy Condition , and enter the following information:
a. In the Identifier field, enter an identifying name.
b. From the Ruleset list, select the application ruleset in which you want to enforce this restriction.
c. In the Apply To: field, enter Data-Admin-Operator-ID .
3. On the Pages & Classes tab, enter the following information:
a. In the Page Name field, enter OperatorID.
b. In the Class field, enter Data-Admin-Operator-ID .
4. Click Definition and then enter the following conditions:
a. In the Conditional logic section, enter a name for the condition.
b. In the Policy Conditions section, in the Condition field, enter the same name that you provided
in the Conditional logic field.
c. In the Column source column, select .pyUserIdentifer.
d. In the Relationship column, select Is equal.
e. In the Value column, select OperatorID.pyUserIdentifer.
5. Click Save.
6. In the header of Dev Studio, click Records > Security > Access Control Policy .
7. Create an Access Control Policy rule with the following details:
a. In the Identifier field, enter a name for the rule.
b. In the Action field, select Read.
c. In the Ruleset field, enter any rulesets in the application for which you want to enforce this
restriction.
d. In the Applies To field, enter Data-Admin-Operator-ID .
 8. Click Definition, and then enter the name of the Access Control Policy condition rule that you create in
Step 4 to the Permit access if field.
9. Save the rule form.

Restricting access to operator information in Pega 8.5

Configuring dynamic system settings
Access Control Policy rule

Understanding project roles and personas

For the best user experience, define how users interact with your application by understanding what roles
and personas your project requires. When you know who uses your application, and how, you can update
the interactions to provide the most relevant content to users.

To enable customers to start using your application, define operators and access groups. By creating
operators and access groups, you specify which elements of your application users can access. As a result,
you ensure that every user can access only the features that are relevant to their role. You can increase
efficiency exposing users only to data that they need, and improve workload management in your
application.

For relevant training materials, see the Organization records and Creating and managing teams of users
modules on Pega Academy.

Operators

An operator defines a unique identifier, password, preferences, and personal information for a user.
Create operators so that people and processes can access your application.

Learning about access groups

An access group is a group of permissions within an application. Pega Platform uses these permissions
for operators, external system access, and background processes. You define an access group for
operators who have similar responsibilities. For example, most applications allow case managers to do
actions that are different from the actions of regular operators, so case managers and regular
operators belong to different access groups.

Creating a team

To increase productivity and facilitate distribution of the workload in your application development
process, create a team. You can then assign work to team members, and speed up resolution of your
cases by providing the team with collaboration tools.

Collaborating on cases

Complete your Microjourney faster by providing collaboration tools for your application users, such as
customer service representatives (CSRs). Through a transparent exchange of messages in an open
discussion, CSRs can resolve cases faster and with better effect.

Creating a Microjourney for customer success

Adding personas to organize users
Engaging with stakeholders to define a Microjourney

Operators
An operator defines a unique identifier, password, preferences, and personal information for a user. Create
operators so that people and processes can access your application.

For example, in an application for reviewing loan requests, you can create operators for customer service
representatives (CSRs), reporting managers, and an administrator to manage the application from the
technical side.

By creating operators you provide access for users and processes to your application so that processing
work can happen, and so that business processes can reach successful resolution. You can create operators
not only for users, but also for automated, unattended processes. Unattended operators are robotic
automation virtual machines (VMs). The system generates unattended operators for each registered VM in
a robotic process automation (RPA) solution. Creating unattended operators increases the automation of
your business processes, lowers costs, and speeds up work resolution.

Creating operators gives you the following benefits:

Increased security
Every operator can have a unique password with which to log in to your application. As a result, you
protect your data and operations from inappropriate or random users.
Improved routing of work
Every operator has an individual queue of assignments to complete that Pega Platform refers to as a
worklist. Additionally, you can give an operator access to a work queue that groups assignments that
are available for members of a specific team. For every operator, you can specify the level of relevant
skills, for example, you can indicate that an operator is a highly advanced Java developer, or speaks
French fluently. Grouping assignments and defining skillsets improves the routing of work and ensures
that an application assigns tasks to the most appropriate users. For every operator, you can also
define periods of unavailability and a substitute worker or work queue to ensure continuous case
processing.
Relevant access type
You can define which data and operations an operator can access and perform in your application. For
example, you can ensure that only a manager can approve or reject new job candidates, or that a CSR
can access all information that a case requires to reach resolution. Consequently, the users of your
application can perform only relevant actions and process their work faster.

The following figure summarizes the options that are available for operators in Pega Platform applications:

The characteristics of an operator

Clusters and operator IDs

After you save a new, or update an existing operator ID instance, the change might not be reflected on
another node in a cluster until the Pega-RULES agent on that node performs the next system pulse —
typically after no more than 60 seconds. Unlike instances of most other Data- classes, the system saves
operator ID instances to the rule cache. As a result, until the next time that the rule cache is synchronized,
one node might access a stale copy from its rules cache.

Bulk operator load

To save time, you can create operator ID instances by importing a comma-separated values (CSV) file, such
as a Microsoft Excel spreadsheet.

Operator ID property
After a requestor logs in, the operator ID identifier is available on the pxRequestor page as the
pxUserIdentifier property.

Operator IDs and external identity providers

If you implement authentication by using an external identity provider (IdP), the login process accesses IdP
for authentication and ignores the password in this operator ID instance. However, the system still requires
an operator ID data instance for each user.

Operator passwords
The system saves passwords for operator IDs as hashed values in the PegaRULES database, by first salting
the clear text password value and then hashing it using the default bcrypt algorithm. The system uses two
property types when changing the password: Password type for the New Password field, and Text type for
the Confirm Password field. The Data-Admin-Operator-ID.pyPwdCurrent property stores the hashed
password after the password passes validation.

Creating an operator ID

Provide users with access to your application by creating operator IDs. When you create an operator
ID, you can specify the background and general information about the user, define application access,
and configure password credentials for the user.

Defining operator contact information and application access

Define contact information and application access for an operator so that all operators can
communicate and access the required applications. The access groups that you specify affect which
applications an operator can access and what their role is.

Defining work routing settings for an operator

For continuous and efficient workload management and routing, define skills, work groups, and work
queues for operators. As a result, an operator can receive work based on skill set and team
membership. For reporting purposes and advanced routing use cases, configure the reporting
structure.

Defining operator availability

Ensure that the workflow in your organization is uninterrupted by defining operator availability and
substituting operators that can receive work when the operator is unavailable. As a result, you ensure
that the processing of your business cases continues even when some of the users are unavailable to
perform work.

Defining security information for an operator

Ensure that your organization complies with security policies by defining security information for the
operators in your system. You can manage operator authentication, passwords, and license types, to
allow rule check out, and enable or disable the operator. As a result, operators can access your
application safely, and then perform only the actions that are relevant to their roles.

Deleting operators

To ensure that only designated workers can access your application, you can disable access for users
that are no longer active, for example, when they no longer work in your organization.
 Bcrypt hashing algorithm for Password property types
Understanding Requestor Type data instances
General tab on the Class form
Defining security information for an operator

Creating an operator ID
Provide users with access to your application by creating operator IDs. When you create an operator ID, you
can specify the background and general information about the user, define application access, and
configure password credentials for the user.

For example, in a banking application, create operator IDs for customer service representatives (CSRs) who
review loan requests, and the manager to whom the CSRs report.
Before you begin: To create an operator ID, you must have the pxCanManageUsers privilege, which is
part of the PegaRULES:SecurityAdministrator role.

1. In the header of Dev Studio, click Create Organization Operator ID .

2. In the Short description field, enter the full name of the new operator.
The value that you enter populates the Full name field in the operator contact information on the
Work tab. The maximum length of the description is 64 characters.
3. In the Operator ID field, enter a unique identifier.
When you enter the identifier, consider the following guidelines:
In addition to letters and digits, the identifier can include the following characters: period (.),
single quote ('), tilde (~), underscore (_), exclamation point (!), ampersand (&), octothorpe (#)
and no more than one at (@) character. Avoid using the forward slash (/) or backslash (\)
characters in the identifier.
An operator ID can consist of a maximum of 128 characters.
Special processing applies to any user identifier that begins with the word External. Use such
identifiers only when defining external operators that use Directed Web Access (DWA) for one-
time processing of assignments.
Avoid using system as an operator ID name. This term is reserved and refers to agents.
4. Click Create and open . Result: The operator rule form is displayed on the page and you can
continue to add information about the user. For example, you can configure access settings or provide
organizational information.

What to do next:

Define an access group and contact information for the operator. For more information, see Defining
operator contact information and application access.
Define organizational information for the operator. For more information, see Defining work routing
settings for an operator.
Define a password for the operator. For more information, see Defining security information for an
operator.

Adding an operator by using the organizational chart

Operators

Defining operator contact information and application access

Define contact information and application access for an operator so that all operators can communicate
and access the required applications. The access groups that you specify affect which applications an
operator can access and what their role is.

For example, you can configure access settings so that a user can access a Loan requests application both
as a manager and as a customer service representative (CSR).
Before you begin:

Create an operator as described in Creating an operator ID or Adding an operator by using the

organizational chart.
To view an application's access settings, you must have the pxCanManageUsers privilege, which is
part of the PegaRULES:SecurityAdministrator role.

1. In the header of Dev Studio, click Configure Org & Security Organization Operators .
2. On the Operators tab, select the operator that you want to edit.
 Tip: To find your operator faster, in the Search Text field, enter the operator name, and then click
Search.
3. Optional: To more quickly distinguish between operators, on the Profile tab, in the Contact
Information section, provide an operator image:
a. Click Choose File.
b. In the files window, select a graphic file that you want to use, and then click Open.
c. Click Upload Image. Result: The image is visible after you save the operator record.
4. Provide basic information about the operator:
a. Optional: To inform users how to address the operator, in the Title field, enter a relevant
personal title. For example: Enter Mr, Mrs, or Dr.
b. Optional: To provide personal information about the operator, complete the First Name and
Last name fields.
c. In the Full name field, enter a value that you want to use to represent the operator across your
system.
By default, the system autopopulates the Full name field with the value that you provide in the
Short description field when you create an operator ID. The operator's full name is visible, for
example, in the list of operators.
d. Optional: To inform users about the job title of the operator, complete the Position / job title
field. For example: Enter Software engineer .
e. Optional: To provide the contact information of the operator, complete the Phone and Email
fields.
The system uses the email address to send email correspondence to the operator.
5. In the Application Access section, list the access groups that the operator can access at run time:
a. In the Access Group field, enter an access group that you want to associate with the operator.
Tip: To see the roles in an access group, click the Expand row icon.
b. Optional: To provide additional roles and access to additional applications, click Add item, and
then in the Access Group field, enter another access group. For example: You can provide
multiple roles for a user within one application, such as a manager role and a CSR role.
c. Indicate the default access group by selecting a relevant radio button. Result: When a user logs
in, the system directs the user to the application and role that the default access group defines.
For example, if you define LoanRequests:Managers as a default access group, the user logs into the
Loan requests application with a manager role.
6. In the Localization section, list the default locale and time zone of the operator.

What to do next: Before you can save the operator record, you need to define the organizational unit of
the operator in your organization. For more information, see Defining work routing settings for an operator.

General tab on the Class form

Learning about access groups
Operators

Defining work routing settings for an operator

For continuous and efficient workload management and routing, define skills, work groups, and work
queues for operators. As a result, an operator can receive work based on skill set and team membership.
For reporting purposes and advanced routing use cases, configure the reporting structure.

For example, when you define the reporting manager of an operator, the manager might receive
notifications about the operator's progress on a case.
Before you begin: Create an operator so that a user can access your application. For more information,
see Creating an operator ID or Adding an operator by using the organizational chart. Every operator has a
unique worklist that accumulates tasks that the specific operator can retrieve. Additionally, an operator can
access a work queue that collects tasks for a team to which the operator belongs. Any team member can
pick up tasks from a work queue. Another name for a team is a work group.

For an automated selection of tasks to process, operators can use the Get Next Work logic. Get Next Work
automatically prompts users with an assignment that currently has the highest urgency in work queues and
work groups that the operator can access.

1. In the header of Dev Studio, click Configure Org & Security Organization Operators .
2. On the Operators tab, select an operator that you want to edit.
Tip: To find your operator faster, in the Search Text field, enter the operator name, and then click
Search.
3. On the Work tab, in the Organizational unit section, define the affiliation of the operator within the
 organization by clicking Update, and then provide a relevant organization, division, and unit. For
example: For an organization, enter the name of your company, for example, UPlusTelco, and then
provide a division and unit, such as BankingOperations for a division and Mortgages for a unit.
4. In the Team field, enter a work group to which the user belongs.
A work group defines routing of tasks and a reporting manager of the user.
For example: If you create Team A to review mortgage requests and Team B to investigate issues
with mortgage operations, the two teams can use separate areas of your application so that the work
is logically separated.
5. Optional: To assign a user to multiple work groups, click Add a work group, in the text box enter a
work group, and then select the radio button next to the work group that you want to set as the
default.
6. Optional: To enhance the reporting options of your application, in the Reports to field, enter the
reporting manager for the user.
7. Optional: To enable routing of tasks based on a skillset, in the Skill field, enter the ability of the user,
and then in the Rating field, enter the level of the ability.
You can apply a rating from 1 to 10, where 10 implies the highest level of the skill.
For example: To indicate that a user is a fluent speaker of French, in the Skill field, enter French, and
then in the Rating field, enter 10.
8. Optional: To allow the user to process assignments from a work queue that corresponds with the
user's work group, in the Work queue section, click Add item, and then provide a work queue and an
urgency threshold.
During Get Next Work processing, your application ignores assignments with urgency lower than the
urgency threshold. For more information about Get Next Work, see Customizing the Get Next Work
logic.
9. Optional: To assign the user to multiple work queues, click Add item, and then repeat step 8.
10. Optional: To trigger the Get Next Work algorithm to retrieve assignments from the work queues of
the user first, select the Get from work queues first check box.
Otherwise, Get Next Work picks up the top assignment on the user worklist, and accesses work queues
only if this user's worklist is empty.
For example: If a user is a member of the Team A to review mortgage requests, the Next Get Work
algorithm suggests assignments that the application routes to the Team A work queue first and then
moves to the assignments from the user's individual worklist.
11. Optional: To trigger the Get Next Work algorithm to retrieve assignments from all work queues that
correspond with the team that you provided in step 4, select the Use all work queue assignments
in user's team check box.
12. Optional: To trigger the Next Assignment item to consolidate assignments from all of the work
queues of the user, sort by assignment urgency, and return the most urgent assignment in any work
queue, select the Merge work queues check box.
If you select the Use all work queue assignments in user's team check box in step 11, the system
selects the Merge work queues check box by default and you cannot clear this check box.
13. Click Save.

Fields for operator teams, work queues, and schedules

Operators

Defining operator availability

Ensure that the workflow in your organization is uninterrupted by defining operator availability and
substituting operators that can receive work when the operator is unavailable. As a result, you ensure that
the processing of your business cases continues even when some of the users are unavailable to perform
work.

1. In the header of Dev Studio, click Configure Org & Security Organization Operators .
2. On the Operators tab, select an operator that you want to edit.
Tip: To find your operator faster, in the Search Text field, enter the operator name, and then click
Search.
3. Optional: To allow applications to route additional assignments to the worklist of the user that the
operator ID identifies, on the Work tab, in the Availability section, select the Operator is available
to receive work check box.
If you leave the check box cleared, the operator can log in, enter work items, or complete assignments
that are already in the worklist. The operator can receive work from other operators and from a
manager.
4. Optional: To define the working days and national holidays for the operator, in the Business
Calendar field, select the relevant calendar. For example: Enter USDefault.
 5. If the operator might be unavailable in the future, in the Scheduled absences section, in the
Unavailable form and To from, define a time period during which the operator is unavailable to
perform work. For example: If the operator has a scheduled medical leave between January 1 and
January 15, select the relevant dates.
6. Optional: To define more periods of unavailability for an operator, click Add item, and then repeat
step 5.
7. Optional: To define how an application routes work when the operator is unavailable, in the When
unavailable section, in the Substitute operator type list, select who or what work queue receives
work:
To route work to another operator, select Operator.
To route work to a list of assignments for a team, select Work queue.
8. Optional: To determine a substitute for the unavailable operator at run time, in the Decision tree to
find substitute field, enter a decision tree that evaluates conditions and finds another assignee for
the assignment.
Based on your configuration in step 7, select a decision tree that returns either an operator ID or a
work queue.
9. Optional: To identify the operator ID or work queue name of a substitute for new assignments that an
application routes to the unavailable operator, enter a relevant value in the Default to assignee
field:
To route work to a specific user, enter the operator ID of the user.
To route work to a team's list of assignments, enter the work queue.
The system uses the value that you provide if you do not specify the decision tree to determine a
substitute operator or the decision tree does not return a result.
10. Click Save.

Creating an operator ID
Creating a team
Adding work queues to a team
Creating work groups

Defining security information for an operator

Ensure that your organization complies with security policies by defining security information for the
operators in your system. You can manage operator authentication, passwords, and license types, to allow
rule check out, and enable or disable the operator. As a result, operators can access your application safely,
and then perform only the actions that are relevant to their roles.

1. In the header of Dev Studio, click Configure Org & Security Organization Operators .
2. On the Operators tab, select an operator that you want to edit.
Tip: To find your operator faster, in the Search Text field, enter the operator name, and then click
Search.
3. On the Security tab, in the Access Settings section, secure access to your application with a
password:
a. Click Update password.
b. In the Change Operator ID Password dialog box, in the New password field, enter the new
password.
c. In the Confirm new password field, reenter the password.
d. Click Submit.
Note: If the operator is provided with Pega Platform, enter a password that is consistent with your
security policies, and then send the new password to the enabled operator.

The system converts the password to a hash value by using the salted bcrypt algorithm. The Storage
Stream (BLOB) column of the pr_operators table contains the hashed value. By using the View XML
action, you can discover only the hashed form of any operator password.

For more information about security polices, see Security policies.

4. If the operator is an unattended operator, select the This is an unattended operator (robot) check
box.
Unattended operators are robotic automation virtual machines (VMs). The system generates
unattended operators for each registered VM in a robotic process automation (RPA) solution.
5. Optional: To allow this operator to update rules in rulesets that use rule checkout, select the Allow
rule check out check box.
6. Optional: To authenticate this operator only through external authentication facilities, select the Use
 external authentication check box.
7. Optional: To prompt the operator to change their password the next time the operator logs in, select
the Force password change on next login check box.
8. Optional: To disable the operator, select the Disable Operator check box.
9. Optional: In the Starting activity to execute field, specify the first activity that the system runs
after authentication for this user is complete.
The default is Data-Portal.ShowDesktop .
10. In the License type list, indicate the operator type:
To indicate that the operator is a person who does business operations by using an application or
customer-created interface, select Named.
To indicate that the operator is an abstract user to run agents, services, and other background
processes, or an external user that interacts with the application through the Directed Web
Access feature, select Invocation.

For unattended operators, the system selects Invocation by default.

11. Click Save.

Operators
License compliance
Checking out a rule

Deleting operators
To ensure that only designated workers can access your application, you can disable access for users that
are no longer active, for example, when they no longer work in your organization.

You cannot delete an operator when a data instance, such as an organization unit or work queue, still
references the operator. To save time, instead of deleting all of the references individually, change the
operator password and mark the user as unavailable.

1. Ensure that the user that you want to delete is not logged in.
2. Transfer or complete all assignments in the work queue for the user.
For more information, see Transferring an assignment.
3. Update the password to a value that is unknown to the user, so that the person can no longer log in.
For more information, see Defining security information for an operator.
4. Ensure that the user has no rules checked out. If any rules are checked out, sign on and delete or
check in the checked-out rules.
You cannot delete an operator ID if the operator has rules checked out. Ensure that the operator
deletes or checks in all rules in their personal ruleset. For more information, see Checking in a rule.
5. Mark the user as unavailable to receive work, and then define the user's departure date and a
substitute operator.
For more information, see Defining operator availability.

Operators

Learning about access groups

An access group is a group of permissions within an application. Pega Platform uses these permissions for
operators, external system access, and background processes. You define an access group for operators
who have similar responsibilities. For example, most applications allow case managers to do actions that
are different from the actions of regular operators, so case managers and regular operators belong to
different access groups.

Access group names have the format application name:access group name. For example, for the MyApp
application, you can define the MyApp:Administrators access group for administrators and the MyApp:Users
access group for regular operators.

Operators can belong to multiple access groups. You select one of the access groups as the default, which
is used when the operator initially logs in. If an operator belongs to multiple access groups, the operator
can switch between groups. Only one access group is in effect at any given time during a session.

When you create an access group, you define permissions and settings that are used for operators who
belong to that access group and who use the application defined for that access group. These permissions
and settings include the following:

Access roles and privileges

The portal layout
The work pools that are available
The types of work items that operators can work on
The rulesets that are displayed at the top of the ruleset list
Details of rule caching for performance
For developers, the initially displayed ruleset and version for rules that they create

Access groups and ruleset lists

When an operator logs in, Pega Platform looks for an access group in the following order until an access
group is found, and uses that access group to assemble the operator's ruleset list:

1. The default access group defined on the Profile tab of the Operator ID form
2. The default access group for the Org Division that is identified on the Work tab of the Operator ID
form
3. The default access group for the Org that is identified on the Work tab of the Operator ID form
4. The default access group for the appropriate requestor type

Access groups and external systems

An access group determines the ruleset list that is available to an external system that requests services.
The following data instances and rules reference access groups directly, or indirectly by specifying an
operator:

Listener data instances

Service package data instances
Agent rules
Agent schedule data instances

When effective
When you save an access group, active requestor sessions on the current node that are associated with
that access group are immediately updated. Requestors at other nodes in a cluster are updated when the
next system pulse occurs on their nodes.

Facilities provided to unauthenticated (guest) requestors

Guest users, or unauthenticated requestors, typically have access to only the rules in the rulesets in the
PRPC:Unauthenticated access group, as referenced in the requestor type instance named pega.BROWSER.

Caution: You should review Security tab of each activity in the rulesets, to verify that the Require
authentication to run check box is not selected if you update the:

pega.BROWSER requestor type to reference a different access group, or

PRPC:Unauthenticated access group to make additional rulesets available to unauthenticated users.

The clipboard for a guest requestor does not include pages for the operator ID, organization, division, or
organization unit.

Viewing access groups and operators

You can view all the access groups or view only the groups that reference an application. You can see
all the access groups across the Pega Platform applications and the operators who have access to
those applications.

Creating an access group

An access group is a group of application permissions that are used by an operator, external system,
or background process. Create an access group to define the actions that are allowed when such an
entity uses an application.
 Assigning work pools to an access group

Work pools are the case types in which users in an access group are allowed to create cases. You
specify the work pools that are available to an access group.

Granting portal access to an access group

Associate a portal with an access group to control which workspaces or web channels are available to
users while they work in your application.

Configuring tools access

The Access Manager Tools tab provides information about the authorizations that users have to the
tools you can secure in your application. Use Access Manager to configure the actions that access
groups can do with tools.

Managing access roles

General tab on the Class form
Understanding Requestor Type data instances

Viewing access groups and operators

You can view all the access groups or view only the groups that reference an application. You can see all
the access groups across the Pega Platform applications and the operators who have access to those
applications.

1. To view all the access groups in Pega Platform, complete the following steps.
You can also view the operators in a group.
a. In the header of Dev Studio, click Configure Org & Security Groups & Roles Access Groups .
b. The fields on this page allow you to learn more about access groups and operators for the current
application.
Search text – Filter the list to display only those access groups with a specific text value in
the name or description.
View in Excel – Click to export access group information and operator counts to Microsoft
Excel file.
Name – Click the access group name to open the access group instance.
Description – A short description of the access group.
Operators – The number of operators associated with this access group as defined in the
operator ID instance. Click the number to display the list of operators.
2. To view only the groups that reference the current application, click Configure Application
Structure Access Groups and Users . The names of the operators in each group are also displayed.
3. To view the operators who belong to a selected access group, complete the following steps.
a. Open an existing access group from the navigation panel by clicking Records Security Access
Group and selecting an instance.
b. On the Operators tab, review the operator ID instances that reference this access group. You
can click a row to open an operator ID record.
The following information is displayed for each operator:
Full name
Operator ID
Job position
Date and time of last sign-on
4. To view the operators who are assigned to a particular organization, division, or unit, complete the
following steps.
a. Display the organizational chart by doing one of the following steps.
Click Configure Org & Security Organization Organizational Chart .
Open the rule form for the organization, division, or unit, and go to the Chart tab.
b. Select any node within the organization.
c. Right-click to open the pop-up panel and click View Operators.
5. To view all operators, do one of the following.
Click Configure Org & Security Organization Operators .
In the navigation panel, click Records Organization Operator ID .

Operators
General tab on the Class form
Creating an access group
An access group is a group of application permissions that are used by an operator, external system, or
background process. Create an access group to define the actions that are allowed when such an entity
uses an application.

Before you begin: To create an access group, you must have the pzCanAlterRoles privilege, which is
included in thePegaRULES:SecurityAdministrator role.

1. In the Dev Studio header, click Create Security Access Group .

2. Enter a short description for this access group data instance.
3. In the Access Group Name field, enter a name. As a best practice, use the format of an application
name followed by a single colon and a description of the job or user function of the users or other
requestors who belong to this access group.
Do not use an asterisk character(*), parentheses (), or spaces in an access group name. Begin the
name with a letter and use only letters, digits, dash, ampersand, period, and colon characters.
For example: ConsumerLoans:Supervisor
4. Click Create and open . Result: The access group is created in a ruleset for the application that you
are currently logged in to. You can change the ruleset by clicking Edit next to the ruleset name.
5. In the Application section, in the Name field, press the Down Arrow key and select the name of the
application that this access group can access.
6. In the Application section, in the Version field, press the Down Arrow key and select the version of
the application that this access group can access.
When a user logs in, the ruleset names and ruleset versions identified in the application rule are added
to the user's ruleset list.
7. Grant portal access to the access group.
8. Add roles to the access group.

Learning about access groups

Assigning work pools to an access group

Work pools are the case types in which users in an access group are allowed to create cases. You specify
the work pools that are available to an access group.

Before you begin: Complete the following task before assigning work pools to an access group: Creating
an access group.

1. Create an access group, or open an existing instance from the navigation panel by clicking Records
Security Access Group and selecting an instance.
2. On the Advanced tab, in the Name field of the Work Pools section, list the work pools that are
accessible to this access group.
a. In the Name field, press the Down Arrow key and select a work pool.
b. To add more work pools to the access group, click Add item and select a work pool.
c. To select the user's default work pool, click the button next to the work pool name.
As a best practice, select the work pool that contains the case types in which users that belong to
this access group most often create cases. This selection determines the default work pool that
appears on the top of the Application Explorer tree when you open an application.

Work pools and access groups

Work pools are the case types in which users in an access group are allowed to create cases. The work
pools that you add to an access group affect the user experience at run time.

Adding personas to organize users

Work pools and access groups

Work pools are the case types in which users in an access group are allowed to create cases. The work
pools that you add to an access group affect the user experience at run time.

Work pools are classes that are marked as is a class group on the General tab of the class rule form.
A work pool is a named collection of case types in which users that belong to the access group
associated with the work pool are permitted to create cases.
 When you define the access group, in the access group's work pool list, you can enter any class group
for which the container class (the Rule-Obj-Class instance with the same name as the class group)
belongs to a ruleset listed in the Production Rulesets list for the access group or that is available to
users through application rules. This restriction ensures that the rules of the application are available
to users associated with the access group.
At run time, the work pools that you add to an access group appear in the Application menu Switch
Work Pool list of the users who belong to the access group. Work pool names appear in the order in
which you list the work pools for the access group. Tip: If this list contains many work pools, consider
reordering them to display the work pool names alphabetically or in another order that is meaningful
to users.
Leave a work pool list empty if users who create new cases and belong to the access group associated
with the work pool use a composite portal that includes the standard section @baseclass.NewWork.
The cases that such users can create appear on the Cases and Data tab of the Application rule, not in
the access group.
At run time, if you leave a work pool list empty and the Application rule is not used for work pools, the
system behaves in the following manner:
When users that belong to the access group associated with the work pool open an application,
the Application Explorer class autocomplete field is empty, and no classes appear in the tree.
Users that belong to the access group associated with the work pool cannot create cases. The
work pool list does not affect which cases the user can update. The list determines only the types
of cases that the user can create. The assignments that the user can open and update are
determined by access roles and ruleset lists, not by work pools.

Assigning work pools to an access group

Learning about access groups
Working with class groups

Granting portal access to an access group

Associate a portal with an access group to control which workspaces or web channels are available to users
while they work in your application.

1. Open an access group by searching for it or by using the Records Explorer.

Tip: To open your current access group, select the Access group option from the Profile menu.
2. Click the Definition tab.
3. In the Available portals section, click + Add portal.
4. In the Name field, press the Down Arrow key, and then select a portal.

For example, select pxPredictionStudio to give the data scientists on your team access to the
Prediction Studio workspace.

5. Optional: To make this portal the default for all operators in the access group, select Default next to
the portal name.
6. Click Save.
7. Log off and then log in to Dev Studio.

Result: Users who belong to the access group can switch from their current workspace or web channel to
the portal that you provide.

Building portals
Changing your workspace
Harnesses form - Completing the Design tab
Learning about access groups

Configuring tools access

The Access Manager Tools tab provides information about the authorizations that users have to the tools
you can secure in your application. Use Access Manager to configure the actions that access groups can do
with tools.

You can view all access groups in the application and see a summary of authorizations for each access
group.

You can also customize the tools that appear on the Tools tab. For more information, see Adding custom
tools to Access Manager.

When you expand a tool category, icons indicate whether full access, no access, or conditional access is
granted to members of the access group.

Summarized views can alert you to areas in your business processes that need tighter restrictions. You can
expand the view to edit the authorizations of a role.

Viewing tools authorizations in all access groups

You cannot modify authorizations when viewing all access groups. The view shows you only whether:

Viewing tools authorization for a single access group

Access Manager allows you to view settings for access groups other than your own. You can see the
following information:

Editing tools authorization for a single access group

You can change the access status of a role for all the operators in the same access group.

Access Manager
Application tools

Viewing tools authorizations in all access groups

You cannot modify authorizations when viewing all access groups. The view shows you only whether:

Before you begin: To use the tools tab in Access Manager, you must be logged in as an operator
associated with an access group that contains the PegaRULES:SecurityAdministrator role.

All operators in an access group are authorized to use all the tools listed in a tool category.
No operators in an access group are authorized to use any tools listed in a tool category.
A combination of conditional access and possibly no access to this tool among operators in the access
group.

1. In the header of Dev Studio, click Configure Org & Security Access Manager Tools .
2. Click Application.
3. Select or deselect the applications you want to modify.
4. Click Apply.
5. In the Access Group field, select All Access Groups.
6. The page displays the access groups for the application and their access status for each tool. Expand a
tool category to see the authorization for each tool in the category.

Access Manager
Application tools

Viewing tools authorization for a single access group

Access Manager allows you to view settings for access groups other than your own. You can see the
following information:

Before you begin: To use the tools tab in Access Manager, you must be logged in as an operator
associated with an access group that contains the PegaRULES:SecurityAdministrator role.

Operators in this access group have full access to the tool.

Operators in this access group have no access to the tool. The menu item or UI element is disabled.
A combination of conditional access and possibly no access to this tool among operators in the access
group.

1. In the header of Dev Studio, click Configure Org & Security Access Manager Tools .
2. Click Application.
3. Select or deselect the applications you want to process.
4. Click Apply.
5. Select an access group from the Access Group list. Result: The page displays the tools and their
access status for the access group.
 6. View or edit the tool category.
a. Click an individual access group to edit.
b. Expand a tool category to see the authorization for each tool in the category.

Access Manager
Application tools

Editing tools authorization for a single access group

You can change the access status of a role for all the operators in the same access group.

Before you begin: To use the tools tab in Access Manager, you must be logged in as an operator
associated with an access group that contains the PegaRULES:SecurityAdministrator role.

1. In the header of Dev Studio, click Configure Org & Security Access Manager Tools .
2. Click Application.
3. Select or deselect applications that you want to process.
4. Click Apply.
5. Select an access group from the Access Group list.
6. Expand a tool category to see the authorization for each tool in the category.
7. In the column for the access role to be authorized, click the icon.
8. Select the access type.
Full Access – Grant operators with this role full access to the item.
No Access – Deny operators with this role access to the item. At run time, the system can hide or
deactivate the item.
Conditional – Grant access based on an Access When condition. Select an Access When
condition under which an operator in the access group can access the item.
9. Click OK.

Access Manager
Application tools

Creating a team
To increase productivity and facilitate distribution of the workload in your application development process,
create a team. You can then assign work to team members, and speed up resolution of your cases by
providing the team with collaboration tools.

Before you begin: Ensure that your application can use Cosmos React UI for landing pages. For more
information, see Implementing in Pega Platform. For applications without Cosmos React UI, see Creating a
team. You can also refer to teams as work groups.

1. In
the header of App Studio, navigate to a portal that contains the Teams widget.
2. In
the navigation pane, click Teams.
3. In
the header of the My Teams section, click Create team.
4. In
the Create team window, provide information about the team:
a. In the Name field, enter a unique team name.
b. Optional: To provide more information about the team, in the About field, enter some text that
describes the purpose of the team.
c. In the Manager field, press the Down arrow key, and then select the name of the user who
supervises the work of the team.
d. Click Submit.
5. Add team members:
a. In the My Teams section, click the team name.
b. On the Team page, in the Members section, click the Edit members icon.
c. In the Edit members window, in the text field, press the Down arrow key, and then select a user
name.
d. Click Add.
e. Click Submit.
6. Optional: To edit information about the team, on the Team page, click Actions Edit team
information .

What to do next: Facilitate collaboration in your team by adding the Pulse gadget to your application. For
more information, see Collaborating with users by using Pulse.
 Adding a secondary manager to a team

Increase the visibility of your work by associating your team with more than one manager.

Defining areas of expertise for a team

As a team manager, define areas of expertise for your team to ensure that your application routes
assignments to users with relevant skills.

Deleting a team

Delete a team when it does have any associated users or work queues to reduce complexity in your
application.

Adding work queues to a team

To speed up case resolution, improve workload management in your application by adding work
queues to your team. You can create multiple work queues that collect tasks for users of different
areas of expertise, for example, a work queue that lists tasks for managers.

Creating a work queue

To improve workload management and task routing in your application, create a work queue that
holds assignments for operators and robotic queues. Because you associate a work queue with a
group of users or a robotic queue, you logically and efficiently categorize work inside your
organization.

Creating work groups

Manage work inside your organization logically and efficiently by creating work groups. A work group
connects a manager and a group of reporting users to enable relevant workflow management and
improve communication.

Updating the organizational structure by using the organizational chart

Reflect the growth of your company by creating new elements in your organizational structure. As your
organization develops, you can add new divisions, units, and sub-units that correspond with new
elements of your enterprise. Maintaining an organizational structure can accelerate your application
development, as you can reuse different application elements across your organization.

Inviting collaborators to your application

Adding a secondary manager to a team

Increase the visibility of your work by associating your team with more than one manager.

By default, each team has one manager who supervises the work of the team and can assign, transfer, or
work on assignments in a case.

1. In the navigation panel, click Records Organization Work Group .

2. In the Work Group Name column, click the name of a team.
3. If no operator IDs are listed in the Authorized Managers section, click Add item.
4. In the Manager ID field, press the Down Arrow key, and then select an operator ID.
5. Click Save.

Result: The secondary manager can access the team's work queue but cannot complete assignments or
receive requests for approval.

Creating a team

Defining areas of expertise for a team

As a team manager, define areas of expertise for your team to ensure that your application routes
assignments to users with relevant skills.

1. As the application author or case manager, click My Teams.

 2. In the Members section, click the avatar of a team member.
3. Click Actions Edit profile .
4. Click New skill.
5. In the Skill field, press the Down Arrow key, and then select a skill that is pertinent to the role and title
of the team member.
6. In the Proficiency field, enter an integer from 0 to 10 that rates how competent the team member is
when applying this skill to the assignments in your application.
7. Click Submit

Creating a team

Deleting a team
Delete a team when it does have any associated users or work queues to reduce complexity in your
application.

Before you begin: Ensure that your application can use Cosmos React UI for landing pages. For more
information, see Implementing in Pega Platform. For applications without Cosmos React UI, see Deleting a
team.

1. In the header of App Studio, navigate to a portal that contains the Teams widget.
2. In the navigation pane, click Teams, and then click a team name.
3. On the Team page, click Actions Delete team .
4. In the Delete Team dialog box, enter the reason why the team is no longer required.
5. Click Submit.

Creating a team

Adding work queues to a team

To speed up case resolution, improve workload management in your application by adding work queues to
your team. You can create multiple work queues that collect tasks for users of different areas of expertise,
for example, a work queue that lists tasks for managers.

Before you begin:

Ensure that your application can use Cosmos React UI for landing pages. For more information, see
Implementing Cosmos React UI in Pega Platform. For applications without Cosmos React UI, see
Adding work queues to a team.
Create a team. For more information, see Creating a team.

When you create a new team, your application creates a default work queue for the team.

1. In the header of App Studio, click Preview to navigate to the portal Dashboard that contains the
Teams widget.
2. In the Teams section, click on the name of the team to which you want to add a work queue.
3. In the Work queues section, click Add new.
4. In the text field that appears, define a work queue:
To create a new work queue, enter the name of the work queue.
To add an existing work queue, press the Down arrow key, and then select a work queue.
5. Optional: To add more work queues, repeat steps 3 and 4.

Collaborating on cases
Creating and managing cases

Creating a work queue

To improve workload management and task routing in your application, create a work queue that holds
assignments for operators and robotic queues. Because you associate a work queue with a group of users
or a robotic queue, you logically and efficiently categorize work inside your organization.

For example, create a work queue for customer service representatives (CSRs) who manage loan requests
to ensure that an application routes loan request tasks to users with relevant skill set and qualifications.
Note: When you create an application, the system creates a default work queue and work group. Because
of mutual dependencies, you need to provide a work queue when you create a work group, and when you
create a work group, you need to provide a work queue. Use the default values, and then provide the actual
values after you create your work group and work queue.

1. In the header of Dev Studio, click Create Organization Work queue .

2. On the Create Work queue tab, in the Short description field, describe the purpose of the work
queue. For example: Enter Loan requests .
3. In the Work queue field, enter a name that clearly conveys the purpose of the work queue and its
contents to users of the application.
Tip: For a better distinction between work queues and other organization elements, append the WQ
characters to the work queue name.
For example: Enter LoanRequestsWQ.
4. Click Create and open .
5. On the Work queue tab, in the General section, specify a work queue type:
Choices Actions

a. In the Type list, select Robotic.

b. In the Maximum queue length field, enter an integer that defines
Create a work queue
the maximum number of tasks that a queue can contain.
that distributes
c. In the Maximum automation execution time (seconds) , enter
assignments to a virtual
the maximum amount of time in seconds that the virtual machine can
machine
take to run the assignment before the system cancels the
assignment.

Create a work queue

that distributes In the Type list, select Standard.
assignments to users
6. In the Organization section, specify an organization layer that contains your work queue:
a. In the Name field, enter the name of an organization to which the work queue belongs. For
example: Enter UPlus.
b. In the Division field, enter the work queue division. For example: Enter BankingOperations.
c. In the Unit field, enter the work queue unit. For example: Enter LoanRequests.
d. In the Work group field, enter a work group that you want to associate with a work queue.
A work group consists of a work queue and a manager to which the work queue members report.
7. Optional: To notify operators about new assignments, in the Contacts section, in the text field, enter
the ID of an operator who receives a notification when an application routes work to the work queue.
8. Optional: To add more operators who receive notifications, click Add item, and then enter the
operator ID.
9. Optional: To specify which users can process work in this work queue, in the Roles section, in the
text field, enter the required role for a user to resolve assignments from the work queue.
If you leave this field blank, any user who can access the work queue can process work.
10. Optional: To add more roles, click Add item, and then enter a role.
To process work, a user needs to have at least one role from the set of roles that you specify.
11. Click Save.

Creating an operator ID
Creating a team
Configuring advanced settings for new applications
Copying a rule or data instance
Creating a rule specialized by circumstance

Creating work groups

Manage work inside your organization logically and efficiently by creating work groups. A work group
connects a manager and a group of reporting users to enable relevant workflow management and improve
communication.

For example, at run time, when a user misses a deadline for a task, a reporting manager receives a
notification. Your application determines the manager by using a work group setting.
Note: When you create an application, the system creates a default work queue and work group. Because
of mutual dependencies, you need to provide a work queue when you create a work group, and when you
create a work group, you need to provide a work queue. Use the default values, and then provide the actual
values after you create your work group and work queue.
 1. In the header of Dev Studio, click Create Organization Work Group .
2. On the Create Work Group tab, in the Short description field, briefly describe the purpose of the
group. For example: Enter Loan application reviews .
3. In the Work Group Name, enter a label for the work group.
As a best practice to provide more information in the name, append to the work group name the at
sign (@), followed by your organization name.
For example: Enter Loans@UPlus.
4. Click Create an open.
5. On the Work group tab, in the Settings section, provide basic information about the work group:
a. In the Manager field, enter the ID of a user who is a reporting manager for the group.
b. In the Default work queue field, enter a default work queue to receive work coming into this
work group.
6. Click Save.

Creating a work queue

Creating a team
Adding work queues to a team

Updating the organizational structure by using the

organizational chart
Reflect the growth of your company by creating new elements in your organizational structure. As your
organization develops, you can add new divisions, units, and sub-units that correspond with new elements
of your enterprise. Maintaining an organizational structure can accelerate your application development, as
you can reuse different application elements across your organization.

For a clear visualization of levels in your company, use an organizational chart to add new elements. The
organizational chart displays each level with expandable sub-levels, such as a unit for a division. For
example, when an Engineering division gains a new team, you can create a new unit that visualizes the
new team.
In an organizational structure, an organization reflects your company. A division corresponds with a part of
the company that gathers teams that operate in a similar business sector, such as engineering or human
resources. A unit visualizes a single team. For further granularization, you can create sub-units. For
example, if you need a unit to represent multiple teams that cooperate, a sub-unit might reflect individual
teams. Consider a scenario in which a UPlusTelco organization needs to create an Engineering division. The
division includes a Mobile unit with two sub-units, Prepaid and Postpaid.

You can reuse rules and other elements of your application across organizational layers. For example, reuse
a process for calculating expenses for an entire organization and then specify different maximum amounts
for each division.

1. In the header of Dev Studio, click Configure Org & Security Organization Organizational Chart .
2. On the Organizational Chart tab, add a new organizational element:
Choices Actions

a. Right-click an existing organization.

b. In the list of available options, select Add organization.
c. In the Add Organization dialog box, in the Organization field, enter the name
of your organization.
Add an
Use the organization's short name, ticket symbol, or Internet domain name.
organization
For example: Enter UPlusTelco.
d. Optional: To provide more information about your organization, in the
Description field, enter additional text.
e. Click OK.

a. Right-click the organization to which you want to add a division.

b. In the list of available options, select Add division to organization.
c. In the Add Division dialog box, in the Division field, enter the name of your
Add a
division. For example: Enter Engineering.
division
d. Optional: To provide more information about your division, in the Description
field, enter additional text.
e. Click OK.

a. Right-click the division to which you want to add a unit.

 Choices b. In the list of available options,
Actionsselect Add unit to division.
c. In the Add Unit dialog box, in the Unit name field, enter the name of your unit.
Add a unit For example: Enter Mobile.
d. Optional: To provide more information about your unit, in the Description
field, enter additional text.
e. Click OK.

a. Right-click the unit to which you want to add a sub-unit.

b. In the list of available options, select Add sub-unit to unit.
c. In the Add Unit dialog box, in the Unit name field, enter the name of your unit.
Add a sub-
For example: Enter Prepaid.
unit
d. Optional: To provide more information about your sub-unit, in the Description
field, enter additional text.
e. Click OK.

For example: The following figure shows a sample organization that consists of three divisions. The
Administration division has two units, HR and Office, whereas the Engineering division has one unit, Mobile.
The Mobile unit includes two sub-units, Prepaid and Postpaid.

Organizational chart

What to do next: Associate users with elements of your organization. For more information, see Adding
an operator by using the organizational chart.

Collaborating on cases
Complete your Microjourney faster by providing collaboration tools for your application users, such as
customer service representatives (CSRs). Through a transparent exchange of messages in an open
discussion, CSRs can resolve cases faster and with better effect.

Application users can collaborate by posting Pulse messages, maintaining spaces, and working on
documents.

Collaborating with users by using Pulse

Improve collaboration and conversation among users within a specific context, such as a case, by
adding the Pulse collaboration gadget to your application. By sharing information in Pulse, users can
work together to resolve their work more quickly.

Collaborating with users by using spaces

By creating spaces, you gather users that are professionally connected within a single digital
community, so that they can collaborate on specific areas of interest. When you restricting the
discussion of certain topics to the users of a space, you can avoid broadcasting irrelevant messages to
all users in your application. After joining a space, you can communicate with the members of the
space by using Pulse.

Collaborating on shared content by using documents

By creating documents, you enrich cases with data and ensure that users have sufficient information
to work in a business process. To provide the most relevant content, users can create documents in an
application, attach local files and files from remote repositories, and add external URLs. When you
create a document, you can save time by sharing the file across multiple cases.

Directed Web Access in configuring assignments for external users

When you enable the Directed Web Access (DWA) in your application, anyone who accesses the
Internet, an intranet, or email can process an assignment. When you use this feature, you extend the
reach of your application to employees throughout the enterprise, trusted customers and suppliers,
and anyone else from whom you want to obtain information.

Collaborating with users by using Pulse

Improve collaboration and conversation among users within a specific context, such as a case, by adding
the Pulse collaboration gadget to your application. By sharing information in Pulse, users can work together
to resolve their work more quickly.

In Pulse, users can post, view, and reply to messages, to promptly exchange information. To enrich
messages, users can attach content to posts and style the text. For example, users can bold important
information within the message. Ensure the best-tailored experience when using Pulse by defining default
feed sources, so that users immediately see only the relevant information. By configuring a message
display, you define what elements a message shows, so that users find all the vital information in the Pulse
posts. For instance, you can define a message title to include a link to a case.
You can use Pulse to collaborate in end-user portals when you work on a case, update your user profile, or
view your activity feed. Because Pulse is a reusable tool, you can embed it in other places in your
application. For improved communication in a case context, you can configure Pulse for different case
types, so that users collaborate to reach a case resolution faster. You configure Pulse for a case type
directly in Case Designer.
Note: To configure Pulse for case types, ensure that your application includes UI Kit 15 or newer.To post
and view messages in Pulse, you embed the pxFeed gadget in your application. The pxFeed gadget shows
message replies, messages in cases that you follow, messages that reference users, profile messages,
bookmarked messages, and application messages. Include this gadget within a section or harness in your
application to view the activity feed, for example, in the dashboard of the Case Manager portal. You can use
the gadget to display the feed within a specific context, such as a case, a team, or a custom context. You
can also configure the Pulse gadget so that users can post messages directly to the activity feed, or to show
posts from internal or external data sources, such as the following data page APIs:

D_pxPostRepliesFeed
Retrieves replies to user posts
D_pxFollowedCasesFeed
Retrieves posts to cases followed by users
D_pxMentionsFeed
Retrieves posts that reference users
D_pxProfileFeed
Retrieves posts to user profile pages
D_pxBookmarkFeed
Retrieves posts that users bookmark
D_pxPosts
Retrieves posts for a case, rule, custom, or operator context.

Examples of collaboration in Pulse

The following scenarios are examples of how you can use Pulse to increase collaboration:

Customer service representatives and product managers that resolve customer issues
Account executives that track a sales opportunity
Marketing personnel that discuss a campaign design
Financial services professionals that approve a loan or credit card request

Collaborate on cases by completing the following tasks:

Adding the Pulse gadget to your application

Provide a collaboration tool for users of your application by adding the Pulse gadget to your
application. By posting, viewing, and commenting on messages, users can work together to resolve
cases faster.

Enabling users to post messages in the activity feed

Enable users to post messages in an activity feed for a specific context. For example, a user can make
release announcements in the context of an application for all the application users to see.

Creating feed sources for activity feeds

Inform users about events that are relevant to them by creating feed sources for messages from
internal or external data sources. After you create a feed source, you can include it in a user activity
feed.

Adding feed sources to activity feeds

Ensure that users can view relevant messages by adding a feed source to their activity feed. For
example, you can add an external feed source, so that customer service representatives (CSRs) that
work with finances can see posts about currency rates.

Determining default feed sources

Ensure that users see only relevant posts by specifying which feed sources Pulse displays by default.

Configuring Pulse for case types

Provide case workers, such as customer service representatives (CSRs), with a collaboration tool for
open discussion of their work, by configuring Pulse. To accelerate case type development, configure
Pulse directly in the case type settings.

Configuring display of Pulse messages

To ensure that users see relevant information about a Pulse message, such as an icon or the profile
image of the users posting and replying to messages, customize the message display.

Choosing a context for Pulse messages

Choose a context for your conversation in Pulse to control who can receive notifications, view, and
reply to the messages that you post.

Posting a message in Pulse

Post a message in Pulse to share information, for example, the status of a case, or to ask a question in
a conversation thread.
 Replying to a message in Pulse

You can reply to a message in Pulse to continue a conversation.

Configuring Pulse email notifications

Inform users in real-time about updates to their Pulse conversations by sending email notifications. In
Pulse, you can choose to receive emails when another user references you, likes your messages, posts
on your profile, posts comments on a conversation in which you participate, or posts a comment on a
case that you follow. As a result, you enhance communication and speed up case resolution.

Enhancing a message in Pulse

You can change the format or content of a message before you post the message in Pulse. By
controlling the presentation of your message and the information that supports it, you can
communicate more effectively with other users.

Managing Pulse messages

Actively manage messages in Pulse so that you can quickly find relevant conversations or
attachments.

Creating a task in Pulse

To manage case work that needs to be completed within a specific period of time, create a task in
Pulse and assign the task to other case users or to yourself. For example, you can assign a task to
yourself as a reminder to upload address documents to a Car Loans case by the end of the day.

Configuring Pulse for case types

Adding the Pulse gadget to your application

Provide a collaboration tool for users of your application by adding the Pulse gadget to your application. By
posting, viewing, and commenting on messages, users can work together to resolve cases faster.

Users that post Pulse messages can make their posts more meaningful by adding attachments, including
links, or by formatting the text.

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

2. Expand the User Interface category, and then click Section.
3. Open a section in which you want to add a Pulse gadget.
4. Add the Pulse gadget:
If you edit the section in the View editor, click Add Data display Embedded section .
If you use a full section editor, click Structural, and then drag Embedded section to a place in
the layout where you want to display Pulse.
5. In the Section include modal window, in the Section field, enter pxFeed.
6. Click Submit.
7. Click Save.

What to do next: Create feed sources that you can add to activity feeds. For more information, see
Creating feed sources for activity feeds.

Collaborating with users by using spaces

Enabling users to post messages in the activity feed

Enable users to post messages in an activity feed for a specific context. For example, a user can make
release announcements in the context of an application for all the application users to see.

Users can view their activity feeds in the Case Manager and Case Worker portals when they click the Pulse
menu option.

1. In Dev Studio, search for the pyPulseWrapper section.

2. Override the pyPulseWrapper section that includes the pxFeed section.
3. On the Design tab of a section or harness, click the pxFeed section.
4. Open the Layout Properties panel by clicking the Settings icon.
 5. On the Parameters tab, in the Configure post settings section, select the Enable post check box.
6. In the Context key field, define the context for posting messages by entering a key value. For
example: Enter: Application.pxInsName
7. In the section, select the message types that users can post:
To allow users to post public messages, select Message.
To allow users to post private messages, select Private post.
To allow users to create and assign tasks, select Task.
Result: The post types are displayed in a menu when you open Pulse and click Post. For more
information, see Posting a message in Pulse.
8. Optional: Update the description of a selected message type:
a. Next to the message type, click the Edit icon.
b. In the Feed name field, update the description.
c. Click Done.
9. Click Submit.
10. Click Save.

Creating an embedded section

Creating feed sources for activity feeds
Adding the Pulse gadget to your application

Creating feed sources for activity feeds

Inform users about events that are relevant to them by creating feed sources for messages from internal or
external data sources. After you create a feed source, you can include it in a user activity feed.

For example, you can configure a Pulse feed to display posts from members of different departments.
Before you begin: To post and display messages, add the Pulse gadget to your application. For more
information, see Adding the Pulse gadget to your application.

1. In the header of Dev Studio, click Create Process Pulse Feed .

2. In the Pulse feed record configuration section, in the Label field, enter a short description for the
feed source that you want to create. For example: Describe messages that users post for a team by
entering TeamPosts.
3. In the Apply to field, select a class to which this feed source applies.
4. In the Add to ruleset field, select the name of the ruleset that contains the feed source.
5. Click Create and open .
6. In the Feed label field, enter a description for the new feed.
By default, the system populates the feed label with the label that you provide in the Label field in
step 2.
7. In the Data page field, enter the data page that retrieves the messages for the feed.
8. In the fields that appear based on the data page that you choose, configure additional parameters.
For example: If you use the D_pxPostRepliesFeed data page to retrieve replies to user messages, in
the UserID field, enter pxRequestor.pyUserIdentifier.

The system uses this value to fetch replies to the messages that logged-in users post.

9. Click Save.

What to do next:

Personalize the Pulse messages in your application by customizing the message display. For more
information see, Configuring display of Pulse messages.
Add a feed source to a user activity feed. For more information, see Adding feed sources to activity
feeds.
Enable posting Pulse comments in cases. For more information, see Configuring Pulse for case types.

Creating an embedded section

Enabling users to post messages in the activity feed
Adding the Pulse gadget to your application

Adding feed sources to activity feeds

Ensure that users can view relevant messages by adding a feed source to their activity feed. For example,
you can add an external feed source, so that customer service representatives (CSRs) that work with
finances can see posts about currency rates.

Before you begin:

Add the Pulse gadget to your application. For more information, see Adding the Pulse gadget to your
application.
Create a feed source. For more information, see Creating feed sources for activity feeds.

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

2. Expand the User Interface category, and then click Section.
3. Open a section that contains the Pulse gadget.
4. In the pxFeed section, click Edit this section.
5. In the Cell Properties window, click the Parameters tab.
6. In the Configure additional feed sources section, click Add feed source, and then specify the
feed source:
a. In the Name field, enter the name of the feed source that you want to add.
b. Optional: To display messages from the feed source every time a user opens the Pulse gadget,
select the Display feed by default check box.
c. Click OK.
7. Click Submit.
8. Click OK.

Configuring Pulse for case types

Configuring display of Pulse messages
Enhancing a message in Pulse

Determining default feed sources

Ensure that users see only relevant posts by specifying which feed sources Pulse displays by default.

Before you begin: Add a feed source for the activity feed. For more information, see Creating feed
sources for activity feeds Users can override the default settings at run time by filtering messages;
however, the default changes are restored after reloading the page.

1. In the header of Dev Studio, search for the section that contains the pxFeed section that you want to
configure, for example, pyPulseWrapper.
2. On the Design tab of the section or harness, click the pxFeed section.
3. Open the Layout Properties panel by clicking the View properties icon.
4. In the Layout Properties, click the Parameters tab.
5. Next to the feed source that you want to mark as the default source, select the Default check box.
6. Click Submit.

Result: Users can see messages from default feed sources.

Enabling users to post messages in the activity feed

Configuring Pulse for case types

Provide case workers, such as customer service representatives (CSRs), with a collaboration tool for open
discussion of their work, by configuring Pulse. To accelerate case type development, configure Pulse
directly in the case type settings.

When you enable Pulse, case workers can post messages to their colleagues and receive replies. To ensure
that case workers only see relevant messages, you can define default feed sources and post display
conditions.
Before you begin:

Create activity feeds to populate user Pulse feeds with notifications. For more information, see
Creating feed sources for activity feeds.
Ensure that your application includes UI Kit 15 or newer.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. In the case working area, click the Settings tab.
3. In the Pulse section, configure the Pulse settings:
 Choices Actions

In the Display label field, enter a new label.

Change the default
label For example, enter Group chat.

Enable posting Pulse

Select the Allow users to add posts check box.
messages

Define a condition for In the row of a post type that you want to configure, in the Visibility list,
post visibility select when the application displays posts.

a. In the Configure additional feed sources section, click Add Pulse

feed.
b. In the Pulse feed name list, select the source that you want to add.
Add a feed source
c. Optional: To display the feed source default, select the Display feed
by default.
d. Click OK.
4. Click Save.

Posting a message in Pulse

Enhancing a message in Pulse

Configuring display of Pulse messages

To ensure that users see relevant information about a Pulse message, such as an icon or the profile image
of the users posting and replying to messages, customize the message display.

For example, you can configure the messages that your application posts automatically to display your
company logo and a case ID as a title of the message.

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

2. Expand the Process category, and then click Pulse Feed.
3. Open a Pulse feed that you want to edit.
4. In the Feed display settings, in the Icon list, select the type of icon that you want to display in the
message:
Choices Actions

a. In the Icon list, select User.

b. In the User reference field, enter a property that references the
Display a user profile
user whose profile image you want to display
image
For example, to display the profile image of the user who posted
the message, enter .pyUser.

a. In the Icon list, select Icon class.

b. Next to the Icon class field, click the Open the icon class picker
Display an icon that a
icon.
system provides
c. in the Icon class picker window, select an icon that you want to
display next to the Pulse message,

a. In the Icon list, select Image.

b. Next to the Image reference field, click the Show Image Viewer
icon.
Display an image from c. in the Search field, enter a key word or the name of the image that
the Image Catalog you want to use, and then click Find.
For example, to view the different default logos that the system
provides, enter Logo.
d. Select the image.
5. In the Title list, select a display format for the title of the message:
To display the title as a value, from the list, select Property, and then in the Property
reference field, enter a property that stores the value that you want to use.

For example, to display a case label as a title, select .pyLabel.

 To display the title as a section, from the list, select Section, and then in the Section reference
field, enter a property that references the section that you want to use.
6. In the Time field, enter the property that retrieves the time at which a user adds the message. For
example: Enter .pxUpdateDateTime.
7. In the Message type field, select a display format for the message:
To display a message as plain text, select Message, and then in the Property reference, enter
a custom property.
To display a message as a section, select Section, and then in the Section reference, enter a
property that references a custom section.
8. Optional: To allow users to comment on a message, in the Comments section, select the Allow
comments check box, and then, enter the custom property from the data page that uniquely
identifies the feed item, for example, Application.pzInsKey.
9. Click Save.

Viewing your activity feed

Enhancing a message in Pulse

Choosing a context for Pulse messages

Choose a context for your conversation in Pulse to control who can receive notifications, view, and reply to
the messages that you post.

Open Pulse in one of the following contexts, based on your audience and message content.

Application developers and stakeholders

In the header of App Studio, click the Toggle Developer collaboration icon.

Case followers and participants

a. Open a case by searching for it or by reviewing the worklists and work queues on your
dashboard.
Members of a team
a. In the navigation panel of the Case Manager portal, click My Teams.
b. Click a team name.
c. In the header of the Team page, click the Toggle pulse icon.
A specific user
a. In the navigation panel of the Case Manager portal, click My Teams.
b. Click a team name.
c. In the Members section, click the Gear icon.
d. In the list that is displayed, click a user name.
e. In the header of the User profile page, click the Toggle pulse icon.

Collaborating with users by using Pulse

Viewing your activity feed

Posting a message in Pulse

Post a message in Pulse to share information, for example, the status of a case, or to ask a question in a
conversation thread.

Before you begin: Option to post a task in Pulse is available only in global Pulse feed and Spaces. To
enable posting a task in a particular context, configure the feed gadget. For more information, see Enabling
users to post messages in the activity feed The following guidance applies to case messages, however, you
can communicate in other contexts, such as a team or application. For more information, see Choosing a
context for Pulse messages.

1. Open a case:
Search for the case.
Click on the case in the worklist or work queue on your dashboard.
2. Add a message by performing the following actions:
To add a message for all case users, click Post Post
To add a message for specific case users, click Post Private post , press the Down Arrow key,
and then select the message recipients.Note: All the users involved in a private conversation can
add more users to the conversation by referencing them, but only the owner can remove users
 from the conversation.
To create and assign a task in Pulse, click Post Task . For more information, see Creating a task
in Pulse.
3. Click Start a conversation, and then enter your message text.
4. Optional: Change the format or content of a message before you post the message in Pulse.
For more information, see Enhance the format or content of your message.
5. Click Post.

Replying to a message in Pulse

Adding a reference in Pulse

Replying to a message in Pulse

You can reply to a message in Pulse to continue a conversation.

The following guidance applies to case messages, however, you can communicate in other contexts, such
as a team or application. For more information, see Choosing a context for Pulse messages.

1. Open a case:
Search for the case.
Click on the case in the worklist or work queue on your dashboard.
2. Find the relevant message in the Pulse conversation.
3. Optional: To acknowledge the message without sending a reply, click the Like icon.
4. Click Comment, and then enter your message text.
5. Optional: Enhance the format or content of your message.
6. Click Post.

Result:

Users are notified of your reply and any attachments that you provide, based on their notification
preferences.

Setting notification preferences

Posting a message in Pulse

Configuring Pulse email notifications

Inform users in real-time about updates to their Pulse conversations by sending email notifications. In Pulse,
you can choose to receive emails when another user references you, likes your messages, posts on your
profile, posts comments on a conversation in which you participate, or posts a comment on a case that you
follow. As a result, you enhance communication and speed up case resolution.

For example, when team members have a Pulse conversation about preparing a loan offer for a VIP
customer, each member can receive email notifications about any activity in the conversation. To save
time, users can also reply to Pulse messages by sending an email.
Before you begin: Define how users want to receive notifications. For more information, see Setting
notification preferences. Receiving Pulse notifications by email helps users resolve cases more quickly,
because users can exchange information directly from their email inboxes without logging in to an
application. In the example of preparing a loan offer, a user can receive email notifications when:

Other users post Pulse messages in the case.

If the message includes an attachment, the user receives the attachment in the email.

Other users reference the email recipient in a Pulse message.

Other users like a message sent by the email recipient.

To resolve the case more quickly, the user can respond to Pulse messages by replying directly to the Pulse
notification from their inbox, without logging in to an application. Pulse then displays the response as a
message in the conversation. To provide more context and information, the user can include an attachment
in their email, that an application attaches to the Pulse message.

You can enable users to receive and respond to Pulse email notifications by performing the following
actions:
 Configuring an email account for Pulse notifications

To notify users about any activity in their Pulse conversations by email, configure an email account to
process Pulse notifications. As a result, users can immediately know about new Pulse messages in
cases that they follow, replies to their messages, and when other users reference them in Pulse
comments. Immediate exchange of information can help users resolve work faster.

Configuring Pulse notifications on additional email accounts

Enhance and categorize communication in your organization by creating multiple email accounts to
send email notifications about Pulse messages. Consequently, users can quickly understand the
context of the message, and as a result, process their work faster.

Enabling users to respond to Pulse email notifications

Enhance communication and accelerate work processing by enabling an option to reply to Pulse
messages by email. When users can post Pulse messages without logging in to an application,
information exchange is faster and more convenient, and as a result, cases reach resolution faster.

Integrating with an email provider

Creating a team
Operators

Configuring an email account for Pulse notifications

To notify users about any activity in their Pulse conversations by email, configure an email account to
process Pulse notifications. As a result, users can immediately know about new Pulse messages in cases
that they follow, replies to their messages, and when other users reference them in Pulse comments.
Immediate exchange of information can help users resolve work faster.

For example, if a customer service representative (CSR) posts a Pulse message with a question about the
maximum loan amount that a customer can receive, and references a manager in the message, the
manager receives an email that contains the message and can immediately respond to the question.

1. In the header of Dev Studio, click Create Integration-Resources Email Account .

2. In the Short description field, briefly describe the purpose of the email account. For example: Enter
Notify about Pulse.
3. In the Account Name field, enter PulseNotifications.
Note: You can have only one account with the name PulseNotifications in the system.
4. Click Create and open .
5. Configure the email account as appropriate.
For more information, see Creating an email account.
6. Click Save.

What to do next:

Allow users to reply to email notifications with text or attachments and post the reply as a response to
the original message. For more information, see Enabling users to respond to Pulse email notifications.
Configure additional email accounts for each application for which you want to send Pulse notifications.
For more information, see Configuring Pulse notifications on additional email accounts.

Integrating with an email provider

Replying to a message in Pulse
Posting a message in Pulse
Collaborating with users by using spaces

Configuring Pulse notifications on additional email accounts

Enhance and categorize communication in your organization by creating multiple email accounts to send
email notifications about Pulse messages. Consequently, users can quickly understand the context of the
message, and as a result, process their work faster.

For example, you can configure an email account, such as HRServices@example.com, to send Pulse emails
from the HR Services application, or SalesAutomation@example.com, to send Pulse emails from the Sales
Automation application, so that users can quickly identify which application sends the notification.
Before you begin: Create an email account for your application. For more information, see Creating an
email account.

1. Copy the pyPulseNotificationsEmailAccount data transform that belongs to the Pega-Social ruleset, to
your application ruleset:
a. In the navigation pane of Dev Studio, click Records.
b. Expand the Data Model category, and then click Data Transform.
c. Click Create.
d. In the Label field, enter a new name for the rule.
e. In the Add to ruleset list, select your application ruleset.
f. Click Create and open .
2. On the Definition tab, in the Source column for the Param.PulseNotificationsEmailAccount target, enter your
email account name, as in the following figure:

Data transform for additional email accounts

3. Click Save.

Configuring an email account for Pulse notifications

Enabling users to respond to Pulse email notifications
Configuring Pulse email notifications
Integrating with an email provider

Enabling users to respond to Pulse email notifications

Enhance communication and accelerate work processing by enabling an option to reply to Pulse messages
by email. When users can post Pulse messages without logging in to an application, information exchange
is faster and more convenient, and as a result, cases reach resolution faster.

For example, in a sales automation scenario, a Pulse discussion occurs about converting a prospect to a
customer in a case. A sales person can quickly add comments to a post and attach a related document by
replying to an email notification, without logging in to the application.
Before you begin:

Create the PulseNotifications email account. For more information, see Configuring an email account
for Pulse notifications.
By default, the system looks for an email account with the name PulseNotifications so that it can
process the Pulse notification emails. All applications in the system use this account to process their
Pule notification emails. If you want to configure a different email account for your application, see
Configuring Pulse notifications on additional email accounts.

Users can receive Pulse notification emails in cases that they follow and for which they choose to receive
notifications. Users also receive emails when other users reference them in Pulse posts, or like their posts.
You can allow users to quickly post attachments or text as replies by responding to emails instead of
logging in to the application.

When users reply to emails, Pulse immediately fetches replies from Outlook, Gmail, Yahoo, iPhone, and
Android email clients.

Note: Users cannot post replies to Pulse by responding to the email notifications that they receive when
other users like their messages.

To enable users to respond to Pulse email notifications, you need to create a relevant service package in
your application, copy an existing service email rule and adjust it to your needs, and then create an email
listener.

1. Create a service package in the application ruleset:

a. In the header of Dev Studio, click Create Integration-Resources Service Package .
b. In the Short description field, briefly describe the purpose of the service package. For
example: Enter Pulse email replies.
c. In the Service Package Name field, enter a label for the service package. For example: Enter
PulseEmailReplies.
d. Click Create and open .
e. In the Context section, in the Processing mode list, select an option that matches your
application, depending on whether your application is stateless or stateful.
f. In the Service access group field, enter the access group of your application.
Ensure that the access group that you want to use can access service methods.
g. Clear the Requires authentication check box to bypass authentication and allow Pega Platform
to invoke service methods.
h. To use TLS/SSL for service REST rules that belong to this service package, select Require
TLS/SSL for REST services in this package.
For more information, see Service Package form - Completing the Context tab.
i. Select the Suppress Show-HTML check box.
j. Click Save.
2. Create a service email rule by copying an existing rule:
a. In the header of Dev Studio, click Configure Integration Services Service Definitions .
b. Expand Service Email in package PulseEmailService class PegaSocial-Message.
c. Click pzCreatePulseReply.
d. Click Save as.
e. In the Label field, enter a new name for the rule.
f. In the Customer Package Name field, enter the name of the service package that you created
in step 2. For example: Enter PulseEmailReplies.
g. In the Customer Class Name field, enter a service class name.
h. In the Add to ruleset list, select your application ruleset.
i. Click Create and open .
j. In the Primary Page section of the Service tab, ensure that the Primary page class field
stores the PegaSocial-Message value.
k. In the Service activity section, ensure that the Activity name field stores the pzPostReplyFromMail
value.
l. On the Request tab, ensure that the Message header and Message data sections store the
same values as the pzCreatePulseReply service email rule.
m. On the Response tab, ensure that the value of the Message type list is None to avoid receiving
blank emails when users reply to Pulse emails.
n. Click Save.
3. Create an email listener rule:
a. In the header of Dev Studio, click Create Integration-Resources Email Listener .
b. In the Short description field, describe briefly the purpose of this listener.
c. In the Listener Name field, enter a label for the listener.
d. Click Create and open .
e. On the Properties tab, from the Startup option list, select the appropriate option for running
the listener, depending on your requirements.
For more information about creating email listeners, see Creating an email listener.
f. In the Email Account field, enter the email account for the listener that you use for sending
emails with Pulse notifications.
g. In the Service information section, in the Service package field, enter the service package
that you created in step 2.
h. In the Service class field, enter the name of the service class name that you entered in the
Customer Class Name field in step 3.
i. In the Service method field, enter the name of the service email that you created in step 3.
j. On the Processes tab, ensure that the No Attachments check box is cleared, so that
attachments can be sent to email replies.
k. Click Save.

What to do next: Manage your listeners in Admin Studio. For more information, see Managing listeners.
 Configuring Pulse email notifications
Creating a Service Email rule
Creating an email listener
Managing listeners

Enhancing a message in Pulse

You can change the format or content of a message before you post the message in Pulse. By controlling
the presentation of your message and the information that supports it, you can communicate more
effectively with other users.

You can enhance a message by using the following techniques:

Formatting a message in Pulse

You can use text formatting to change the look and feel of your message.

Uploading an attachment in Pulse

You can upload attachments to the messages that you post. By controlling what type of information
supports the text of your message, you can communicate more effectively with other users.

Adding links to a message in Pulse

You can include inline information to the messages that you post to Pulse. By providing a link to a
relevant image or resource, you add context to a conversation.

Adding a reference in Pulse

You can reference a user, space, document, or case in a comment or post that you add to Pulse. By
including a link in your message that opens a relevant user profile, user group, application document,
or work item, you can add context to a conversation.

Tagging an existing message in Pulse

You can tag a message in Pulse to associate it with similar messages. By categorizing messages, you
can help users find information that is required to resolve a case.

Tagging a new message in Pulse

You can tag a message in Pulse to associate it with similar messages. By categorizing messages, you
can help users find the required information to resolve a case.

Posting a message in Pulse

Viewing your activity feed

Formatting a message in Pulse

You can use text formatting to change the look and feel of your message.

1. Enter your message text in Pulse, but do not post the message.
2. Click the View formatting help icon.
3. Apply a syntax from the Style, Lists, or Headings section to the relevant text in your message. For
example: You can apply bold style to important words in the message.
4. Click Post.

Enhancing a message in Pulse

Uploading an attachment in Pulse

You can upload attachments to the messages that you post. By controlling what type of information
supports the text of your message, you can communicate more effectively with other users.

1. Enter your message text in Pulse, but do not post the message.
2. Click the Add attachment icon.
 3. Upload a file from your local system or an external system, such as Box.com.
4. Click Post.

Result: The attachment is associated with your message and any relevant case.

Enhancing a message in Pulse

Extension points and supporting rules for attachments

Adding links to a message in Pulse

You can include inline information to the messages that you post to Pulse. By providing a link to a relevant
image or resource, you add context to a conversation.

1. Enter your message text in Pulse, but do not post the message.
2. In your message text, enter the URL to an image or resource.
3. Click the View formatting help icon.
4. Apply a syntax from the Images or Links section to the URL in your message text.
5. Click Post.

Enhancing a message in Pulse

Adding a reference in Pulse

You can reference a user, space, document, or case in a comment or post that you add to Pulse. By
including a link in your message that opens a relevant user profile, user group, application document, or
work item, you can add context to a conversation.

Before you begin: Enable search indexing for work items.

1. Enter your message text in Pulse, but do not post the message.
2. Place your cursor in the message text, and then enter @.
3. Select whether you want to reference a user, space, document, or case.
4. Type one or more characters to narrow the list of results and select a value from the list that is
displayed.
5. Click Post.

Result: Individual users and users of the spaces that you reference are notified about your message, based
on their notification settings. Documents and cases that you reference become links in your message.

Restricting case references in Pulse

You can control which cases users can reference in the messages that they post to Pulse. By limiting
the choices in the list of suggested cases, you can help users create messages more quickly.

Differentiating case references in Pulse

You can control which icons and descriptions are displayed to users when they reference a case in
Pulse. By visually differentiating the choices in the list of suggested cases, you can help users create
messages more quickly.

Adding feed sources to activity feeds

Restricting case references in Pulse

You can control which cases users can reference in the messages that they post to Pulse. By limiting the
choices in the list of suggested cases, you can help users create messages more quickly.

1. Open the Work-.pyGetCasesForReferencesFromIndex report definition by searching for it or by using

the Records Explorer.
2. Copy the report definition to an open ruleset in your application.
3. Create a filter condition that excludes cases or instances of a specific case type.
a. Click the Query tab.
b. In the Edit filters section, click Add filter. Result: The Condition field is populated and its
value is added to the Boolean expression in the Filter conditions to apply field.
c. In the Column source field, enter .pxObjClass.
 d. In the Relationship list, select Is not equal.
e. In the Value field, enter the class of the case type to exclude.
f. Optional: To exclude more case types, click Select values.
4. Click Save.

Differentiating case references in Pulse

Adding a reference in Pulse
Finding rules by class

Differentiating case references in Pulse

You can control which icons and descriptions are displayed to users when they reference a case in Pulse.
By visually differentiating the choices in the list of suggested cases, you can help users create messages
more quickly.

1. Open the @baseclass-.pyGetMentionsJsonString activity by searching for it or by using the Records

Explorer.
2. Copy the activity to the class of a case type.
3. On the Steps tab of the Activity form, expand step 3.
4. Provide a custom icon for cases or instances of the case type.
a. In the PropertiesName column, locate the field that is set to local.MentionedIcon.
b. In the PropertiesValue field, replace the default value with the location of your custom icon.
5. Provide a custom description for cases or instances of the case type.
a. In the PropertiesName column, locate the field that is set to local.mentionedDetails.
b. Click the Build an expression icon next to the PropertiesValue field. Result: The JSON string
that determines the list of suggested cases is displayed.
c. Find the AdditionalInfo JSON object in the string.
d. In the call to the @getLocalizedText method, replace the "Case" parameter with your custom
description enclosed in quotation marks.
6. Click Save.
7. Refresh your browser session.
8. Optional: Repeat this procedure for each class, or case type, that you need to differentiate.

Restricting case references in Pulse

Adding a reference in Pulse
Finding rules by class

Tagging an existing message in Pulse

You can tag a message in Pulse to associate it with similar messages. By categorizing messages, you can
help users find information that is required to resolve a case.

The following guidance applies to case messages, however, you can communicate in other contexts, such
as a team or application. For more information, see Choosing a context for Pulse messages.

1. Open a case:
Search for the case.
Click on the case in the worklist or work queue on your dashboard.
2. Hover over a message.
3. Click the Show more icon, and then click Add tag.
4. Add a tag to the message.

To create a new tag, enter a unique name in the Add tag field.

To reuse a tag, press the Down Arrow key in the Add tag field, and then select a tag.

5. Click Add.
6. Click OK.

Tagging a new message in Pulse

Enhancing a message in Pulse

Tagging a new message in Pulse

You can tag a message in Pulse to associate it with similar messages. By categorizing messages, you can
help users find the required information to resolve a case.

1. Enter your message text in Pulse, but do not post the message.
2. Place your cursor in your message text, and then enter #.
3. Type one or more characters, and then select a tag from the list of matching results. Result: If no
matches are found, a new tag is created from the text that you entered.
4. Add more tags after entering a blank space after each tag.
5. Click Post.

Tagging an existing message in Pulse

Enhancing a message in Pulse

Managing Pulse messages

Actively manage messages in Pulse so that you can quickly find relevant conversations or attachments.

Use the following techniques to manage your messages in Pulse:

Viewing your activity feed

You can view your activity feed to find Pulse messages that you post or bookmark, and messages that
are related to you. By filtering information from an aggregate source, you can find a specific
conversation without opening individual cases.

Bookmarking a message in Pulse

You can bookmark a message in Pulse that you consider important, so that you can easily find the
message later in your activity feed.

Removing a bookmark in Pulse

You can remove a bookmark in Pulse when a message is no longer relevant to you.

Following messages from a specific user

Follow users to view the posts that they make in your Pulse activity feed.

Unfollowing messages from a specific user

Unfollow users so that you no longer see their posts in your Pulse activity feed.

Deleting a message in Pulse

You can delete a message in Pulse when it is no longer relevant to a conversation.

Collaborating with users by using spaces

Viewing your activity feed

You can view your activity feed to find Pulse messages that you post or bookmark, and messages that are
related to you. By filtering information from an aggregate source, you can find a specific conversation
without opening individual cases.

1. In the navigation panel, click Pulse.

2. Optional: To find a message more quickly, filter the results.
a. Click the Filter icon.
b. Clear the check box next to a type of message to exclude it from the results.
c. Click Apply.
3. Review the list of results to find your message.
4. Optional: To continue the conversation for this message, click Comment.

Replying to a message in Pulse

Bookmarking a message in Pulse

You can bookmark a message in Pulse that you consider important, so that you can easily find the message
later in your activity feed.

The following guidance applies to case messages, however, you can communicate in other contexts, such
as a team or application. For more information, see Choosing a context for Pulse messages.

1. Open a case:
Search for the case.
Click on the case in the worklist or work queue on your dashboard.
2. Hover over the message, and then click the Show more icon.
3. Click Bookmark.

Removing a bookmark in Pulse

Posting a message in Pulse
Viewing your activity feed

Removing a bookmark in Pulse

You can remove a bookmark in Pulse when a message is no longer relevant to you.

1. In the navigation panel, click Pulse to open your activity feed.

2. Click the Filter icon.
3. Select the My bookmarked messages check box.
4. Click Apply.
5. Hover over a message, and then click the Show more icon.
6. Click Remove Bookmark.

Bookmarking a message in Pulse

Posting a message in Pulse
Viewing your activity feed

Following messages from a specific user

Follow users to view the posts that they make in your Pulse activity feed.

Before you begin: Ensure that your dashboard includes the Pulse activity feed widget. For more
information, see Adding a widget.

1. Open the user profile for the user that you want to follow.
For example, you can open the profile of a team member by completing the following steps.
a. Click My Teams.
b. Click a team name.
c. In the Members section, click the name of the user.
2. Click Follow.

Result: Your user profile displays the users whom you follow and the users who are following you. An icon
indicates whether a user is online.

Collaborating with users by using spaces

Unfollowing messages from a specific user

Unfollow users so that you no longer see their posts in your Pulse activity feed.

Tip: If you have the user's profile open, you can quickly unfollow the user by clicking Following.

1. From your Profile menu, select Profile.

2. In the Following section, click See all.
3. Click the Check box icon for each user that you want to unfollow.
4. Click Submit.

Following messages from a specific user

Deleting a message in Pulse

You can delete a message in Pulse when it is no longer relevant to a conversation.

1. Find the message in your activity feed.

2. Hover over the message, and then click the Show more icon.
3. Click Delete.

Posting a message in Pulse

Replying to a message in Pulse

Creating a task in Pulse

To manage case work that needs to be completed within a specific period of time, create a task in Pulse
and assign the task to other case users or to yourself. For example, you can assign a task to yourself as a
reminder to upload address documents to a Car Loans case by the end of the day.

Before you begin: In Dev Studio, enable the task post type.

For more information, see Enabling users to post messages in the activity feed.

1. Open a case:
Search for the case.
Click on the case in the worklist or work queue on your dashboard.
2. Click Post Task .
3. Enter a name for the task.
4. In the Assignee field, press the Down Arrow key, and then select a user to assign the task.
5. In the Due date field, select the date and time by which the task should be completed.
6. Optional: In the Additional details box, enter more information about the task.
7. Click Create.

Result: Your Pulse interface and the Pulse interface of the assignee display the task. If the assignee does
not complete the task, they receive two reminder notifications based on their notification preferences. The
first notification arrives when half of the time till the due date elapses, and the second one appears after
the deadline. For example: If the due date is in 24 hours, the assignee receives the first notification after
12 hours and the second one after 24 hours.What to do next: The task assignee can click the Complete
icon when they finish work on the task. The assignee and you can comment on and like the task. You can
edit the task when it is still open, and reopen the task after its completion.

Posting a message in Pulse

Choosing a context for Pulse messages

Collaborating with users by using spaces

By creating spaces, you gather users that are professionally connected within a single digital community, so
that they can collaborate on specific areas of interest. When you restricting the discussion of certain topics
to the users of a space, you can avoid broadcasting irrelevant messages to all users in your application.
After joining a space, you can communicate with the members of the space by using Pulse.

In spaces, users can collaborate and exchange information by posting Pulse messages and attaching
documents. To distribute work, plan the outcomes, and ensure that every space member is on track, you
can create a task board, and then manage tasks in a comprehensible and clear way, even if members of a
space belong to different teams. For instance, you can populate a task board that is visible to managers
and members of various teams that cooperate on a joint project together. To make your content more
relevant, create a subspace that gathers users within a space. For example, you can create a subspace for
CSRs that work together on a particular project, so that you do not involve the whole team.
For example, you are a team leader and you want to hire new members for your team. To discuss
prospective candidates with management, you can create a Hiring space that includes the manager, senior
manager, and director of the team.

The following tasks can help you collaborate with other users by using spaces:

Creating a space

You can create a space to collaborate with other users in your application on a specific area of
interest, for example, to discuss training for new hires in your team.
 Joining a space

You can join a space to become a member of the space and discuss a topic involving a specific area of
interest with other members, for example, to exchange views about prospective hiring candidates for
your team.

Communicating with members of a space

You can communicate with the members of a space by using Pulse to discuss relevant topics, for
example, training for new hires.

Pinning content to a space

A pin is a reference to a file, URL, document, case, or space. By pinning content that supports a
discussion in a space, you can communicate with the space members more effectively. For example,
you can pin the job profiles of prospective candidates to the Hiring space.

Managing a space

You can manage a space by updating the details about the space, and by adding and removing
members. You can also approve or reject requests to join the space and set another member as the
owner of the space. By managing a space, you can ensure that the space has correct information and
relevant members.

Adding content to a space

By attaching relevant correspondence and documentation, you can centralize the supporting
information for a space. For example, you can add sales orders from your customers so the orders are
available for other users of your space.

Creating a subspace

A subspace is a space within a space. You can create a subspace to collaborate on a subtopic that is
related to the topic of the parent space. For example, you can create an Annual Day subspace within
the Events space.

Monitoring and tracking tasks

Monitor and track work within your team by using the task board, which displays the status of tasks.
You can also create tasks and update the task status from the board.

Granting Super Admin privileges to users

You can provide users with Super Admin privileges to manage and edit any space, even if they are not
members of the space.

Searching for Pulse messages in spaces

To more quickly access the information that you need, search for Pulse messages within the context of
a space. For greater accuracy, apply filters, such as keywords or message authors.

Collaborating with users by using Pulse

Creating a space
You can create a space to collaborate with other users in your application on a specific area of interest, for
example, to discuss training for new hires in your team.

1. In the navigation pane, click Spaces.

2. Click Create space.
Note: The user who creates a space becomes the owner of the space.
3. Enter a name for the space.
4. Optional: In the Description field, enter a description for the space.
5. Select a space type.
Public – All users in your application can see the space and join it. The owner can also invite
users to the space.
Private – All users in your application can see the space and request to join it. The owner can
 also invite users to the space.
Unlisted – The space is displayed only for the owner and users who are invited by the owner to
join the space.
6. Optional: To create tasks in Pulse and use a task board in your space, select the Enable task
tracking check box.
You can also enable task tracking after you create a space by clicking Edit space on the Activity tab.
For more information, see Monitoring and tracking tasks.
7. Optional: Update the image for the space. Result: The image is displayed as a part of the space
preview in the Spaces landing page and is also displayed when you open the space.
8. Click Done.

Result: A space is created with a Pulse interface for discussions and sections that contain the space
details. The space is displayed in the Spaces landing page.

Joining a space
Communicating with members of a space
Managing a space
Collaborating with users by using spaces

Joining a space
You can join a space to become a member of the space and discuss a topic involving a specific area of
interest with other members, for example, to exchange views about prospective hiring candidates for your
team.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Join a space by doing one of the following actions:
To join a public space, in the space preview, click Join space.

You can instantly collaborate with the members of the space.

To join a private space, in the space preview, click Request access.

When the owner approves the request, you receive a notification, after which you can collaborate
with the members of the space.

To join an unlisted space, wait for an invitation from the owner of the space.

When the owner invites you, you receive a notification, after which you can collaborate with the
members of the space.

Tip: To leave a space, click Actions Leave .

What to do next: Discuss topics with the members of the space by using Pulse and pin content to the
space to add meaning to the discussions.

Communicating with members of a space

Pinning content to a space
Managing a space
Collaborating with users by using spaces

Communicating with members of a space

You can communicate with the members of a space by using Pulse to discuss relevant topics, for example,
training for new hires.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.
 Join the space to become a member. For more information, see Joining a space.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space in which you want to start or continue a discussion.
4. On the Activity tab, use Pulse to communicate with the members of the space.
Tip: Select the types of notifications that you receive for the space by clicking Notification
preferences and enabling the Override at instance level option.
5. Optional: Add content to support discussions by uploading or pinning files, URLs, and documents, or
by pinning cases and other spaces in your application.
6. Optional: If you are the owner of the space, moderate discussions and content by deleting the
messages, attachments, and pins that are irrelevant or inappropriate.

Pinning content to a space

Collaborating with users by using spaces

Pinning content to a space

A pin is a reference to a file, URL, document, case, or space. By pinning content that supports a discussion
in a space, you can communicate with the space members more effectively. For example, you can pin the
job profiles of prospective candidates to the Hiring space.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.
Join the space to become a member. For more information, see Joining a space.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space to which you want to pin content.
4. On the Board tab, click Add content.
5. In the Create pin box, select a pin type.
6. Select a type of content to pin to the space:
For the Case, Document, or Space pin types, press the Down Arrow key, and then choose a
value from the field that appears, or upload a file.
For the URL pin type, enter a URL in the field that appears.
7. Optional: Update the pin title and image. Result: The title and image appear in the pin preview on
the Board tab.
8. Click Pin to space .
9. Optional: To pin the current space to another space, click Actions Pin to space , and then choose or
create the spaces to which you want to pin the current space.
10. Optional: To pin the content to another space, perform the following actions:
a. Hover over the pin, and then click the Show more icon.
b. Click Repin.
c. In the dialog box, choose or create the spaces to which you want to pin the content.

Result: The content that you pin appears on the Board tab of a space, which provides a comprehensive
overview of the content that is linked to the space.

Editing a pin in a space

Edit a pin in a space to update the title and image or to add a new image to an existing pin.

Deleting a pin from a space

Delete a pin from a space when the pin is no longer relevant For example, in the Hiring space, you can
delete the job profiles of candidates who have not cleared interviews.
 Editing a pin in a space
Deleting a pin from a space
Collaborating with users by using spaces
Collaborating on shared content by using documents

Editing a pin in a space

Edit a pin in a space to update the title and image or to add a new image to an existing pin.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.
Join the space to become a member. For more information, see Joining a space.

Note: If you are a member of a space, you can only edit pins that you create.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space in which you want to edit a pin.
4. On the Board tab, search for the pin that you want to edit.
5. Hover over the pin, and then click the Show more icon.
6. Click Edit.
7. Update the pin title, image, or description.
8. Click Submit.

Pinning content to a space

Collaborating with users by using spaces

Deleting a pin from a space

Delete a pin from a space when the pin is no longer relevant For example, in the Hiring space, you can
delete the job profiles of candidates who have not cleared interviews.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.
Join the space to become a member. For more information, see Joining a space.

Note: If you are a member of a space, you can only delete pins that you create.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space from which you want to delete a pin.
4. On the Board tab, search for the pin that you want to delete.
5. Hover over the pin, and then click the Show more icon.
6. Click Delete.

Pinning content to a space

Collaborating with users by using spaces

Managing a space
You can manage a space by updating the details about the space, and by adding and removing members.
You can also approve or reject requests to join the space and set another member as the owner of the
space. By managing a space, you can ensure that the space has correct information and relevant members.

The following tasks can help you manage a space:

Updating details of a space

You can update the details of a space to ensure that the information about the space is correct. For
example, you can update the name of the space.

Managing members of a space

You can ensure that a space has relevant members by adding and removing members. You can also
approve or reject requests to join the space.

Updating the owner of a space

You can update the owner of a space if you do not want to, or cannot own the space. For example, if
you are leaving your organization, you can set relevant members as owners of the spaces that you
own.

Collaborating with users by using spaces

Updating details of a space

You can update the details of a space to ensure that the information about the space is correct. For
example, you can update the name of the space.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space for which you want to update details.
4. On the Activity tab, click Edit space.
5. Do one of the following actions:
Update the name, description, type, or image for the space.
Update the hierarchy by adding, removing, or updating the parent space.

If you add a parent space, the current space becomes a subspace for the parent space. If you
remove the parent space, the current space is no longer a subspace.

6. Click Submit.
Tip: If the space is no longer required, delete the space by clicking Actions Delete .

Creating a subspace
Managing a space
Collaborating with users by using spaces

Managing members of a space

You can ensure that a space has relevant members by adding and removing members. You can also
approve or reject requests to join the space.

Before you begin: Ensure that you have owner or member access to the space:

Create the space to become the owner. For more information, see Creating a space.
The owner of the space sets you as the owner. For more information, see Updating the owner of a
space.

1. In the navigation pane, click Spaces.

 2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space for which you want to manage members.
4. On the Activity tab, in the Members section, click the Manage members icon.
5. Do one of the following actions:
To add members to the space, in the Add new members field, press the Down Arrow key to
select the user that you want to add as a member and click the Add member icon.
To remove members from the space, click the Delete member icon next to the name of the
member.
To approve or reject member requests to join the space, click the Approve member or Reject
member icon next to the name of the user.
6. Click Submit.

Managing a space
Collaborating with users by using spaces

Updating the owner of a space

You can update the owner of a space if you do not want to, or cannot own the space. For example, if you
are leaving your organization, you can set relevant members as owners of the spaces that you own.

Before you begin: Ensure that you have owner access to the space:

Create the space to become the owner. For more information, see Creating a space.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space for which you want to update the owner.
4. On the Activity tab, click Edit space.
5. Click the Change owner icon next to the name of the owner.
6. In the field that is displayed, press the Down Arrow key and select a member to set as the owner.
7. Click the Save icon next to the field.
8. Click Submit.
Note: After you choose another owner, you no longer own the space. However, you continue to be a
member of the space.

Managing a space
Collaborating with users by using spaces

Adding content to a space

By attaching relevant correspondence and documentation, you can centralize the supporting information
for a space. For example, you can add sales orders from your customers so the orders are available for
other users of your space.

You can add any type of file to a space.

1. In the user portal that you use, for example Case Manager, click Spaces.
2. Select the space where you want to add content.
3. In the Recent content section, click the Add content icon, and then do one of the following actions:
Create a new document by using the rich text editor.
Add an existing document to reuse content from another space.
Add a URL, for example an address of a page of your customer.
Upload a local document.
Select a file from an external repository.
4. Optional: To provide only relevant content for the users, grant access to the document to members of
a space or case by performing the following actions:
a. In the Available to section, select Limited.
b. From the Select type list, select Space or Case.
 c. In the Name field, enter the name of a space or case.
5. Click Submit.

Discussing content in a space by using Pulse

To provide additional information to content that you add to a space, you can collaborate with other
users of your application by using Pulse. For example, you can prepare and collaborate on a draft of a
presentation that your team is to deliver.

Pinning content to a space

Collaborating with users by using spaces

Discussing content in a space by using Pulse

To provide additional information to content that you add to a space, you can collaborate with other users
of your application by using Pulse. For example, you can prepare and collaborate on a draft of a
presentation that your team is to deliver.

1. In the user portal that you use, for example Case Manager, click Spaces.
2. Select the space that contains a document that you want to discuss.
3. In the Recent content section, select the document.
4. Use Pulse to discuss the document with other users by performing the following actions:
Click Add attachments to attach files to your Pulse comments.
Click Formatting help for information about the formatting options.
Click Post to send your comments.
5. Optional: Perform additional actions to control document notifications, modify content, add tags, and
so on by using buttons on the right:
To receive notifications for the document when you are not the owner, click Actions and select
Follow.
To modify the document, click Edit.
To add tags to the document, modify your notification preferences for the document, pin the
document to a space, or delete the comment, click Actions and select the relevant option.

Pinning content to a space

Creating a subspace
A subspace is a space within a space. You can create a subspace to collaborate on a subtopic that is
related to the topic of the parent space. For example, you can create an Annual Day subspace within the
Events space.

Before you begin: To create a subspace, you must be a member of the parent space. You can create
subspaces within subspaces. You can also add multiple subspaces to a parent space. However, a subspace
can have only one parent space.

1. In the navigation pane, click Spaces.

2. Choose the spaces in your application to view.
To view the private and public spaces, and unlisted spaces of which you are a member, click All
spaces.
To view only the spaces of which you are a member or an owner, click My spaces.
3. Click the space within which you want to create a subspace.
4. Click Actions Add subspace .
5. Create a subspace by following the steps to create a space.
For more information, see Creating a space.

Result: A subspace is created with a Pulse interface for discussions, a link to the parent space above the
title of the subspace, and sections that contain the subspace details. The subspace is displayed in the
Subspaces tab of the parent space and also in the Spaces landing page.What to do next: Users can
perform the same tasks with subspaces as they can with spaces. A user can join a subspace and members
can communicate with other members of the subspace. The owner can manage the members and the
subspace details, such as updating or removing the parent space.

Joining a space
Communicating with members of a space
 Managing a space
Updating details of a space
Collaborating with users by using spaces

Monitoring and tracking tasks

Monitor and track work within your team by using the task board, which displays the status of tasks. You
can also create tasks and update the task status from the board.

Before you begin: Ensure that tracking tasks is enabled. For more information, see Creating a space.

1. In the navigation pane of the portal that you use, for example Case Manager, click Spaces, and then
choose the space that you want to update with tasks.
2. Click the Tasks tab.
3. Add a task by clicking the Create task icon.
4. Manage your tasks:
To change the priority of a task, drag it up or down within a column.
To add content to a task, click Show more Add content .
To change the status of a task, drag the task from one column to another.
To edit task details, double-click the task.
To delete a task, click Show more Delete .
For more information about the task board, see the Pega Community article Managing team tasks on a
task board.

Managing a space

Granting Super Admin privileges to users

You can provide users with Super Admin privileges to manage and edit any space, even if they are not
members of the space.

Users with Super Admin privileges can perform the following actions in any space:

Mark a space as promoted.

Edit a space: change the space type, edit the name or description, and change the owner and
hierarchy.
Delete a space.
Create subspaces.

1. Create an access group in the application where you want to grant Super Admin privileges to a user.
For more information, see Creating an access group.
2. Create an access role for promoted spaces.
For more information, see Creating an access role by using the access role dialog box.Tip: To save
time, clone an existing access role.
3. Add the PegaSocial-Group class to the access roles.
4. Add the pxSpaceAdmin privilege with level 5 and give access level 5 to the following functions:
Read
Write
Delete
Run a report of rules and instances
Level 5 is the highest level.
5. Add the new access role to the new access group.
For more information, see Adding a role to an access group.
6. Add the new access group to the users to whom you want to give Super Admin privileges, and then
make the newly created access group the default access group.

Creating a space
Creating a subspace
Updating details of a space

Searching for Pulse messages in spaces

To more quickly access the information that you need, search for Pulse messages within the context of a
space. For greater accuracy, apply filters, such as keywords or message authors.
For example, you can filter messages that include the phrase Loan request that a specific user has added.
Before you begin: Enable Search indexing and index Pulse instances. For more information, see Enabling
classes for search indexing. Search results include private and public posts, comments, and attachments
that match the filters that you apply. If the result is a comment, Pulse displays the complete thread so that
you can see the context of the comment. For attachments, the filters evaluate both file names and
contents.

1. In the navigation pane of the portal that you use, click Spaces.
2. Open the space for which you want to search the Pulse messages.
3. On the Activity tab, in the Search field, click Expand search option.
4. In the Filter posts dialog box, define the filters that you want to apply. For example: In the
Contains line, enter Loan request.
5. Click Search.

Result: The results display posts, comments, and attachments that match the applied filters.

Collaborating with users by using Pulse

Collaborating on shared content by using documents
Collaborating with development teams

Collaborating on shared content by using documents

By creating documents, you enrich cases with data and ensure that users have sufficient information to
work in a business process. To provide the most relevant content, users can create documents in an
application, attach local files and files from remote repositories, and add external URLs. When you create a
document, you can save time by sharing the file across multiple cases.

For example, you are an approver for Car Loan cases and you want to discuss the address proof document
for a case with other approvers. You can open the document from the case and use Pulse to consult other
approvers.

Unlike attachments, documents offer the following features:

You can create documents directly in your application by using the built-in rich text editor. When you
create a document by uploading a file, you can provide a name for the document and use the rich text
editor to add a description. You can also update documents later if needed.Note: You cannot annotate
image documents.
Documents are always created within the context of your application, and are not limited to a case, a
space, or a Pulse conversation. However, you can reference the same document from multiple cases
and spaces in your application.
You can use Pulse to discuss a document with other users of your application.

The following tasks can help you share information with other users by using documents:

Creating a document in an application

You can create a document to discuss information with other users in your application, for example, to
discuss a job profile for your team. You can create a document by uploading a file or by using the rich
text editor.

Discussing a document

You can discuss a document by using Pulse to review additional information about a case with other
users in your application, for example, to analyze a faulty sales order.

Attaching content to a case type

Attaching screen captures to a case

Creating a document in an application

You can create a document to discuss information with other users in your application, for example, to
discuss a job profile for your team. You can create a document by uploading a file or by using the rich text
editor.

Note: The user who creates a document becomes the owner of the document.
 1. In the navigation pane, click Documents. Result: The Documents landing page opens.
2. Click Create document.
3. Enter a name for the document.
4. Add content for the document by performing any of the following actions:
Create a new document by using the rich text editor.
Upload a local document.
Select a file from an external repository.
5. Optional: To provide only relevant content for the users, grant access to the document to members of
a space or case by performing the following actions:
a. In the Available to section, select Limited.
b. From the Select type list, select Space or Case.
c. In the Name field, enter the name of a space or case.
6. Click Publish.

Result: The document is added within the context of the application and is displayed on the Documents
landing page.What to do next: Discuss the document with other users by using Pulse, and reference the
cases and spaces that the document is associated with.

Discussing a document
Collaborating on shared content by using documents
Collaborating with users by using spaces

Discussing a document
You can discuss a document by using Pulse to review additional information about a case with other users
in your application, for example, to analyze a faulty sales order.

1. In the navigation pane, click Documents. Result: The Documents landing page opens.
2. Choose the documents to view.
Click All documents to view all the documents in your application.
Click My documents to view only the documents that you own and follow.
3. Click the document that you want to discuss.
4. Use Pulse to discuss the document with other users.
5. Optional: Perform additional actions to control document notifications, modify content, add tags, and
so on.
To receive notifications for the document when you are not the owner, click Actions and select
Follow.
To modify the document, click Edit.
To save an offline copy of the document when the document is an uploaded file, click Download.
To add tags to the document, modify your notification preferences for the document, or pin the
document to a space, click Actions and select the relevant option.
To add followers, attachments, and references to cases, spaces, and other documents, use the
relevant section below the Document details section.

Collaborating on shared content by using documents

Collaborating with users by using spaces
Attaching content to a case type
Attaching screen captures to a case

Directed Web Access in configuring assignments for external

users
When you enable the Directed Web Access (DWA) in your application, anyone who accesses the Internet, an
intranet, or email can process an assignment. When you use this feature, you extend the reach of your
application to employees throughout the enterprise, trusted customers and suppliers, and anyone else from
whom you want to obtain information.

For example, you can configure your application to send an email with a DWA link to someone who has
complained, which they can click, and then answer a feedback question on whether they are satisfied with
the resolution of a complaint. Users might not be customers, so they might not have login credentials to
access the website and application.

Assignments define the parts of case processing that require human judgment, expertise, and data entry
from trained users of the application. Assignments that you send to outside parties are external
assignments. External assignments improve accountability, eliminate the need for phone calls, and give
visibility to the responsiveness of the parties.

To send an external assignment to users, the application includes a specially formatted URL in the text of
an email. When the email recipient clicks the URL, a web browser session opens and submits a once-only
identifier and password to the Pega Platform server.

After authenticating these values, Pega Platform sends an assignment to the user's browser. When the user
completes and submits the assignment, the requestor connection ends. The external user cannot repeat
the assignment or reuse the URL or password because the session is authenticated for one time only.

For security reasons, the URL for an external assignment must be static, which means that it cannot be
generated or altered by JavaScript or other processing at run time. Because of this restriction, the flow
action cannot use AJAX, dynamic select, or SmartPrompt, which require multiple server interactions.

External assignments are instances of the Assign-External class, or of its subclass. The standard activity
Work-.External creates these assignments.

The following run-time events describe the way that users interact with external assignments:

1. A case reaches an external assignment in the life cycle.

2. Your application sends an email to the user who is identified in the routing settings for the external
assignment.
3. The user clicks the URL in the email message, which sends a token to your application for
authentication.
4. The web browser of the user displays the form for the assignment.
5. The user completes the assignment by entering values in the fields on the form and submitting the
form.
6. The session ends and the case moves to the next step in the life cycle.
7. Your application updates the count of web invocations that are used in reports for license compliance.

Sending automatic emails from cases

Learning about approval by email

Creating a Microjourney for customer success

Help your customers reach a successful resolution in their business processes by applying the Pega Express
methodology while working on implementation projects through journeys and microjourneys. When you
focus on one journey at a time, you not only improve how you address the specific needs of your
customers, but also reach results more rapidly.

A journey and a Microjourney

A journey is the series of interactions between a customer and an organization that occur as the customer
pursues a specific goal, such as hiring a job candidate. To deliver results of the highest quality, divide your
journey into smaller units that you can adjust to your customers' requirements. A Microjourney represents a
unit of work that results in a particular outcome, for example, reviewing a job application. For improved
planning and development of your Microjourney, Pega Platform employs the Pega Express methodology
that enhances the experience of building your applications and delivering your projects. A Microjourney has
the following elements as its foundation:

Case types that visualize the path of your business processes

Personas that represent the people that are involved in your processes and the channels that they use
to interact with a case
Data that your processes require to reach a resolution

Efficient Microjourney planning

When you plan your Microjourney, you create draft relationships between cases, personas, and data
objects. This planning phase helps your development team estimate the time and effort that they need to
turn these drafts into permanent objects, so that you can build your application and deliver your projects
faster. In addition, by visualizing all of the key aspects of your case within a single view, you improve how
you understand and communicate the various aspects of development that your Microjourney involves.
For more detailed planning of your application development, you can specify the releases with which you
plan to implement specific elements of your Microjourney. For example, in a hiring process, you can define
a job candidate persona that in the first release of your application can only fill in a questionnaire that
collects personal details. As you further enhance your application, you can indicate that in the second
release the job candidate will also be able to upload scans of required documents.

The following figure presents creating a draft relationship between a case type and a persona:

Associating a persona with a case type

What to do next: Learn how to plan and implement your Microjourney through the following articles:

Application update scenarios for the Pega Express methodology

To start planning your Microjourney in a user-friendly, transparent, and holistic way, first update your
application. As a result, you can visualize the key elements of your cases – case types, personas, and
data – on one screen, so that you can improve your understanding of the needs of your customers.

Adding case types to organize work

To manage your Microjourney efficiently, automate and visualize your business processes by creating
case types. When you implement case types, you organize your work into consistent and logical
phases, collect and control the data that your process requires, and audit information to ensure that
your outcomes are of top quality.

Adding personas to organize users

You can manage users more intuitively through personas, which store comprehensive information
about the roles and access rights of all of the stakeholders in a process.

Adding data objects to organize data

Identify and manage the data that your Microjourney requires by creating data objects for your case
types. When you ensure that users of your application have all of the information required to process
business cases, you speed up case resolution and maximize work efficiency.

Managing application inventory

Plan the development of your application, manage the workload in your team, and prioritize your work
accordingly by following the application backlog on your Inventory landing page. The Inventory landing
page lists features, personas, and draft data associations across your Microjourney, so that your team
can map items to specific releases.

The Microjourney in the Pega Express methodology FAQ

Reach your business goals faster and with greater effect by understanding and implementing the Pega
Express methodology while planning your Microjourney.

Adopting feature-driven development

 Engaging with stakeholders to define a Microjourney

Application update scenarios for the Pega Express

methodology
To start planning your Microjourney in a user-friendly, transparent, and holistic way, first update your
application. As a result, you can visualize the key elements of your cases – case types, personas, and data –
on one screen, so that you can improve your understanding of the needs of your customers.

Note: You only need to update your existing applications that you created in Pega Platform 8.3 or earlier.
All new applications that you create in Pega Platform 8.4 and later support the Pega Express methodology
by default.

The update proceeds in the following order:

1. When you open your existing application in App Studio, a prompt to update your application is
displayed.
2. After you accept an update, your application creates rules corresponding to data objects and
personas. Your application uses an unlocked ruleset or a branch to store the rules.

By default, your application uses logic to choose the best unlocked ruleset. If you want to specify a
ruleset to store the new rules, specialize the pySetUpgradeRuleSet data transform. For more
information, see Data transforms.

3. When the update is complete, you need to merge the new personas and data objects rules.

For more information about merging rulesets, see RuleSet Maintenance wizard.

For more information about merging branches, see Merging branches into target rulesets.

If your application includes built-on applications, update the built-on applications first. If you update your
built-on applications first, when you update your current application, it only references the data objects
from your built-on applications.

By updating your current application first, it creates the data objects that it uses from the built-on
applications. If you update your built-on applications later, it duplicates the data objects. As a result, when
you start by updating your built-on applications, you save time and resources.

Update without built-on applications

During the update, your application performs the following tasks:

Creates new data objects that correspond to all the data types that are present in your application.
Creates personas that correspond to all the access groups in your application that do not have access
to Dev Studio, App Studio, Admin Studio, or Prediction Studio.
Matches releases with color-coded symbols, if your application includes releases. If your application
does not include any releases, it creates new releases.

Update with built-on applications

During the update, your application performs the following tasks:

References existing data objects from the built-on applications to avoid duplicating items, if you
update the built-on applications first.
Creates personas that correspond to all the access groups in your current application and built-on
applications that do not have access to Dev Studio, App Studio, Admin Studio, or Prediction Studio.
Matches releases with color-coded symbols, if your current application or built-on applications include
releases. If your application does not include any releases, it creates new releases.

What to do next: After you update your application, start planning your Microjourney. See Adding case
types to organize work.

For relevant training materials, see the Defining a customer Microjourney module on Pega Academy.
 Adding case types to organize work
Adding personas to organize users
Adding data objects to organize data
Data modeling

Adding case types to organize work

To manage your Microjourney efficiently, automate and visualize your business processes by creating case
types. When you implement case types, you organize your work into consistent and logical phases, collect
and control the data that your process requires, and audit information to ensure that your outcomes are of
top quality.

A case type is a reusable template that represents a business process. For better understanding of your
customers' needs, design your application by describing the stages within a case type, then define the
steps or processes that happen in each stage when the case workers process an actual case. This provides
an easy way to capture objectives in a single view that all case participants, from application designers to
executives and end users, can use to understand how a particular case type works and progresses. Cases
can continue to change throughout their life cycle due to various internal and external events. Depending
on the context of the case, different case workers can work to resolve individual tasks, processes, and
stages. This flexibility helps you achieve your goals in the most effective way.

Maximize efficiency during the case life cycle by implementing the following features:

To support and facilitate resolution of more complex cases, create a hierarchy of parent-child cases.
Organize smaller processes into child cases to resolve for a parent case to reach its end.

For more information, see Case types.

To ensure that the appropriate case worker receives a task, define routing for assignments. You can
assign tasks to a work queue, worklist, or a specific case worker, or you can define routing logic that
automatically chooses the correct assignee at run time.

For more information, see Assigning tasks to users.

To support timely case resolution, define service-level agreements (SLAs) for a case type or specific
stages or tasks within a case. Enrich the SLAs and make them more effective by adding escalation
actions.

For more information, see Completing work on time.

To allow case workers to collect information and feedback from end users, design surveys.
Supplement the surveys with multiple question formats, such as text boxes, sliders, or radio button
matrices.

For more information, see Designing surveys.

What to do next: Add case types to your Microjourney by completing the following tasks:

Creating a top-level case type

Improve work processing in your application by creating top-level case types that visualize business
processes. When you visualize a business process, you can conveniently divide the process into
phases, and then track and manage work with greater ease.

Creating a primary stage

Represent main phases of your business process by creating primary stages in a case life cycle. By
creating stages, you can ensure that your work is divided into logical phases, so that you can track
and resolve the tasks more conveniently.

Adding a sequential process to a stage

Control the order of events in a case by adding a sequential process to a stage. A sequential process
orders related actions that lead to the resolution of a case.

Adding single steps to processes

 Model your business process with basic tasks that users or automations resolve, by adding steps to
your case life cycle. When users complete steps, your case moves closer to its resolution and to
achieving your business goal.

Automating work by creating case types

Engaging with stakeholders to define a Microjourney

Creating a top-level case type

Improve work processing in your application by creating top-level case types that visualize business
processes. When you visualize a business process, you can conveniently divide the process into phases,
and then track and manage work with greater ease.

For example, you can create a top-level case type that represents a hiring process, and then reuse the type
every time when you want to process a job application from a new candidate.

1. In the navigation pane of App Studio, click Case types.

2. In the header of the navigation pane, click Manage.
3. Click New.
4. In the Case type name field, enter a name for the case type.
5. Optional: To reuse assets from another case type, click Advanced, and then select a case type.
6. Click Next.

Result: Your new case type includes a default Create stage with a Create process.What to do next:

Divide work into phases by adding stages to your case type. See Creating a primary stage.
Create child case types that represent dependencies that you resolve before the top-level case type
can reach the resolution. See Creating a child case type.

The Create stage

Case types
Case life cycle elements
Creating a data model from a spreadsheet
Creating a Microjourney for customer success

Creating a primary stage

Represent main phases of your business process by creating primary stages in a case life cycle. By creating
stages, you can ensure that your work is divided into logical phases, so that you can track and resolve the
tasks more conveniently.

Primary stages visualize the main phases of your business process. For example, for a Review job
application case type, you can create stages, such as Conduct screening, Conduct interview, and Approve
candidate.

Before you begin: Define a case type. See Creating a top-level case type.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. On the Workflow tab, click Life cycle.
3. If there are no primary stages defined, click Add life cycle.
4. In the Case life cycle section, click Stage, and then enter a unique name in the text box.
By default, the system creates a stage for each case life cycle that you define.
5. In the Stage property panel, on the General tab, define the transition after this stage is complete:
To move to the next stage, select Automatically move to next stage.
To let the customer service representative decide which stage the case enters, select Wait for a
user action.
To close the case, select Resolve the case, and then define the resolution status and options.
6. Click Save.

What to do next: Organize work within stages by adding processes. See Processes in a case life cycle.

Case life cycle elements

Creating an alternate stage
Processes in a case life cycle
Adding a sequential process to a stage
Control the order of events in a case by adding a sequential process to a stage. A sequential process orders
related actions that lead to the resolution of a case.

For example, if your business case is to review a job application, you can create a sequential process that
includes the following tasks:

Prepare interview questions

Conduct the interview
Prepare the candidate's assessment

Before you begin: Add stages to your case type. See Creating a primary stage.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. On the Workflow tab, click Life cycle.
3. In the Case life cycle section, hover over a stage, and then click More Add process New process .
4. In a new text field, replace the default process label with a descriptive name.
5. Optional: To change the run-time order of a process, drag the process to a different position in the
stage.
6. Click Save.

Result: At run time, the process starts when all steps in the previous process are completed.What to do
next:

Provide meaningful tasks for your process by adding steps. See Adding single steps to processes.
Make your process applicable only to a certain channel, such as a web channel, by defining conditions
to start a process. See Defining conditions for starting a process.

Conditionally starting a process

Adding single steps to processes

Model your business process with basic tasks that users or automations resolve, by adding steps to your
case life cycle. When users complete steps, your case moves closer to its resolution and to achieving your
business goal.

Before you begin: Add processes to stages in your case type. See Adding a sequential process to a stage.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. On the Workflow tab, click Life cycle.
3. In a process, click Step, and then select a step type that you want to add.
4. In the text field, replace the default step label with a descriptive name.
5. Click Save.

What to do next: Start planning your Microjourney by associating personas with your case type. See
Adding personas to organize users.

Adding an automated step to a process

Adding personas to organize users

You can manage users more intuitively through personas, which store comprehensive information about
the roles and access rights of all of the stakeholders in a process.

Personas are a design tool that helps you group users according to the responsibilities that they assume
within a process, the cases on which they work, and the channels that they can access. This grouping
provides for a more granular level of control over the user experience, from defining which stages of a case
belong to which type of user, to customizing the interface to include only the information that a specific
role requires. You can create as many personas as you like, and use them as reference for building access
groups in your application.

For example, when designing a job application review case, you create a job candidate persona and an HR
worker persona. The candidate uses an elegant, consumer-grade mobile app interface, while the HR worker
relies on a more utilitarian, task-oriented web portal with back-office functionalities. During the design
process, you decide that both personas should have access to the first stage of the case, so that both the
candidate and the HR worker can perform relevant actions from their respective interfaces. However, only
HR workers should be allowed to view, advance, and resolve the case, so you assign the rest of the case to
the HR worker persona.

By keeping your personas, access groups, and interfaces parallel, you make the case flow more transparent
and adaptable to future changes.

The following table illustrates the configuration of personas in a credit card dispute:

Personas in a job application review case

Persona Channel Interface type Can resolve case Access group

Candidate Mobile Candidate No Candidate

HR worker Web Case worker Yes Case worker

What to do next: Create and implement personas in your Microjourney by completing the following tasks:

Creating personas

For enhanced planning and understanding of your business processes, add participants to your
Microjourney by creating personas. When you create personas, you group users by their
responsibilities in a process, the channels that they can access, and the cases on which they work.

Associating personas with case types

To clearly visualize the participants of your Microjourney, associate personas with case types in your
application. By adding personas to a Microjourney, you communicate which users are involved in each
phase of your business process, and which channels they can access.

Associating personas with channels

To ensure that the participants of your Microjourney interact with your application in the most relevant
way, create draft relationships between personas and channels. When you associate personas with
channels, you clearly visualize what means of communication your development team needs to
implement, to deliver an efficient and flexible application.

Granting personas access to channels and pages

Start your Microjourney by giving the personas that you create access to relevant portals and pages.
By defining different types of access, you can monitor the actions that your team performs. For
example, you can ensure that only the personas that represent managers can access the Case
Manager portal.

Inviting collaborators to your application

Enhance your application and begin processing your business cases by inviting collaborators with
different skills and roles.

Creating personas with developer portal access

To deliver a flexible application that is useful even in the complex and advanced scenarios, create
personas that have access to developer portals, such as App Studio. When personas use developer
portals, they can be involved in both creating and processing work.

Understanding project roles and personas

Creating personas
For enhanced planning and understanding of your business processes, add participants to your
Microjourney by creating personas. When you create personas, you group users by their responsibilities in a
process, the channels that they can access, and the cases on which they work.

For example, for a hiring process, you can create personas that represent a job candidate, an HR worker,
and a manager.

When you create personas, you define metadata that represents the users of your application. By
visualizing users, you can easily plan and communicate the development of your application.

Before you begin: Define your case type, and then populate the case life cycle with stages, processes,
and steps. See Adding case types to organize work.

1. In the navigation pane of App Studio, click Users, and then click Personas.
2. In the Personas header, click New.
3. In the New persona window, in the Persona name field, provide a descriptive name for your
persona. For example: Enter HR worker .
4. Select an avatar to represent the persona.
5. Optional: To provide more information about the persona, in the Description field, enter additional
text. For example: For an HR worker, enter A user that processes job applications .
6. Click Submit. Result: Your application saves a new persona and adds it to the Personas landing page.
7. Optional: To see which channels a persona uses to interact with case types in your application, on
the Personas landing page, select the Include draft relationships check box.

What to do next: Associate the personas that you create with your Microjourney. See Associating
personas with case types.

Understanding project roles and personas

Operators
Learning about access groups
Creating a team

Associating personas with case types

To clearly visualize the participants of your Microjourney, associate personas with case types in your
application. By adding personas to a Microjourney, you communicate which users are involved in each
phase of your business process, and which channels they can access.

For example, for a hiring process, you can associate a candidate persona and an HR worker persona. This
association indicates that each persona can access different portals in the case, different information about
the process, and perform different actions. While the candidate only provides personal details and uploads
necessary documents, the HR worker processes the details, runs background checks, routes the case for
approval to a manager, and resolves the case.
Before you begin:

Define a case type. See Case types.

To reuse existing personas, define personas for your application. See Creating personas.

When you associate a persona with a case type, you create a draft relationship between the persona and
the case type. To start processing your case, you need to implement the relationship by granting the
persona access to channels.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. In the Persona section of a stage in which you want to add a persona, click Add persona, and then
select a persona that you want to use:
Choices Actions

a. In the personas list, select Create new.

b. In the New persona window, in the Persona name field, provide a
descriptive name for your persona.
Create a new
c. Select an avatar to represent the persona.
persona
d. Optional: To provide more information about the persona, in the
Description field, enter additional text.
e. Click Submit.

Select an existing
 persona In the personas list, select a persona that you want to add.
Choices Actions
3. Click Save.

Result: Your case life cycle displays the personas that you can use when you plan your application
development. By default, App Studio creates a draft relationship between the persona and a web channel
that is at the top of the web channels list in your application.What to do next: To define channels that you
want to provide for the personas, create draft channel associations. See Associating personas with
channels.

Understanding project roles and personas

Associating personas with channels

To ensure that the participants of your Microjourney interact with your application in the most relevant way,
create draft relationships between personas and channels. When you associate personas with channels,
you clearly visualize what means of communication your development team needs to implement, to deliver
an efficient and flexible application.

You can associate a persona with multiple channels, and then assign the channels to different releases. For
example, for a hiring process, you can associate an HR worker with a web channel and a mobile channel. In
the first release of your application, the HR worker can process cases by using a web portal. In the second
release, the HR worker can then also work on a mobile device.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. In the Personas & Channels section, locate the persona that you want to associate with a channel,
and then click Channel.
3. In the channels list, select a channel type that you want to associate with the persona, for example,
Mobile. Result: If you have a channel of the selected type in your application, App Studio adds the
channel below the persona.
4. Optional: To create a new channel, provide details for the channel:
a. In the Channel properties pane, in the Portal list, select Create new.
b. In the New channel dialog box, in the Name field, enter a short description for your channel For
example: Enter Job applications mobile processor.
c. Click Submit.
5. Optional: To change a channel assigned to the persona, in the Channel properties pane, in the list,
select a different channel.
6. Optional: To plan when you want to include the channel in your Microjourney, associate the channel
with a release:
a. In the Additional details section, click Configure release.
b. In the Edit details dialog box, in the Release list, select the release.
c. Optional: To indicate how much time the development team needs to implement the channel, in
the Complexity list, select a relevant option.

Implementing a channel includes completing all the actions necessary for a persona to begin
using a channel, which are configuring a persona to access the channel and the case type,
updating the stage in the case type to support the required use case, and updating the channel so
that the persona can access it in this stage.

Channel complexity affects project estimations and expected development duration.

d. Optional: To provide more information about a channel, in the Comment text box, enter a short
description.
e. When you implement the channel, select the Mark as done check box.
Implementing a channel is the result of configuring a persona, a case type, and the channel itself,
so that the persona can access the channel in a relevant stage of the case type.
f. Click OK.
7. To associate more channels with the persona, repeat steps 2 through 6.
8. Click Save.

Result: Your case life cycle displays the persona with a list of associated channels.What to do next: To
start using personas in your application, give the personas that you create access to channels. See
Granting personas access to channels and pages.

Estimating application development

 Understanding project roles and personas

Granting personas access to channels and pages

Start your Microjourney by giving the personas that you create access to relevant portals and pages. By
defining different types of access, you can monitor the actions that your team performs. For example, you
can ensure that only the personas that represent managers can access the Case Manager portal.

By default, a persona has access to all pages in your application.

Before you begin: Create personas for your application. See Creating personas.

1. In the navigation pane of App Studio, click Users, and then click Access.
2. Locate the column of a persona that you want to edit.
3. In the Portals section, in the Default channel row, in the list, select a default portal for the persona.
A user that you associate with the persona sees the default channel every time they log in to your
application.
4. Optional: To provide access to more channels, in the row that contains another channel, select one
or more check boxes.
5. In the Pages section, select the check boxes for the pages that you want to be available for the user
with the associated role. For example: If you select the A new case type, Documents, and
Reports pages for a role, the users with this role can access only these pages.
6. Click Save.

What to do next: Invite users to your application and associate them with personas. See Inviting
collaborators to your application.

Defining areas of expertise for a team

Inviting collaborators to your application

Enhance your application and begin processing your business cases by inviting collaborators with different
skills and roles.

For example, you can invite members of a development team so that the team can start working on
building your application. When you invite collaborators, you associate them with personas that you create
in your application. Personas define type of access that you grant to the users of your application.
Before you begin: Define types of access for the users of your application. See Granting personas access
to channels and pages.

1. In the navigation pane of App Studio, click Users, and then click People.
2. In the working area, click Invite people to your application.
3. In the Add users to application window, in the autocomplete field, press the Down arrow key, and
then select a user name or email address. Result: If you enter an email address that does not exist,
the system creates a new user for you.
4. In the list, define a type of access that the user has to your application by selecting a role.
When you select a role, you associate a user with a persona. For more information about personas,
see Creating personas.
5. Click Add.
6. Send an email with an invitation to the user by clicking Send invitation.
7. Close the Add users to application dialog box.

What to do next: Analyze what data your case requires to reach a resolution by defining data objects. See
Adding data objects to organize data.

Creating a team
Creating applications
Managing work across your team

Creating personas with developer portal access

To deliver a flexible application that is useful even in the complex and advanced scenarios, create personas
that have access to developer portals, such as App Studio. When personas use developer portals, they can
be involved in both creating and processing work.
For example, a manager can take part in a Microjourney by approving or rejecting cases. The manager
might also add steps to the case life cycle to adjust the process to changing requirements.
Before you begin: Associate a developer portal with an access group for which you want to create a
persona. For more information, see Granting portal access to an access group. By default, in App Studio,
you can create personas without access to developer portals to clearly distinguish between run-time and
design-time application users.

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

2. Expand the Security category and then click Access Group.
3. In the list of the access group instances, select the access group for which you want to create a
persona.
4. In the Persona section, click Create persona with this access group.
5. In the Create persona dialog box, click Submit.
6. To manage the persona access to channels in App Studio, in the Available roles section, select the
Enable page access configuration in App Studio check box.
7. Click Save.

Result: The persona can access a developer portal defined in the access group as well as channels defined
in the persona settings in App Studio.

Adding personas to organize users

Learning about access groups

Adding data objects to organize data

Identify and manage the data that your Microjourney requires by creating data objects for your case types.
When you ensure that users of your application have all of the information required to process business
cases, you speed up case resolution and maximize work efficiency.

Adding data objects to your case life cycles creates draft relationships between the data and your business
processes. By examining these draft relationships, you can optimize work by estimating what information a
specific case requires and then planning how you can acquire this data. For example, if your case
represents a hiring process that includes a Collect personal details stage, you can create draft data objects
such as Address information and Insurance details. As a result, when building your application, you can
clearly visualize the information that is essential to case resolution and clearly communicate the objective
to your development team.

To provide complex solutions for your case types, you can also capture data from external systems. For
example, in a hiring process, you can include a candidate's profile from an external web page.

What to do next: Plan and implement data objects in your application by completing the following tasks:

Associating data objects with case types

Provide the transparency of data that a Microjourney requires by associating data objects with case
types. When you define which data objects you need to create to process your business case, you
improve the overall planning and development of your application.

Implementing draft data objects

Provide data that is necessary to process your business cases and meet your goals by implementing
draft data objects. When you plan your Microjourney, you can associate draft data objects with case
types. By turning these data objects into permanent elements, you ensure that your customers can
process the Microjourney successfully.

Associating attachment categories with case types

To ensure that the workers who process your Microjourney have the relevant information, associate
attachment categories with your case type. Visualizing the attachments required by your Microjourney
helps you to gain a better overview of the information that your application users need to deliver. You
can also communicate to your stakeholders what documents or other attachments are crucial in the
Microjourney.

Associating data objects with case types

Provide the transparency of data that a Microjourney requires by associating data objects with case types.
When you define which data objects you need to create to process your business case, you improve the
overall planning and development of your application.

Before you begin:

Create a case type, and then populate the case life cycle with stages, processes, and steps. See
Adding case types to organize work.
Create personas that visualize groups of users of your application. See Adding personas to organize
users.

When you associate a data object with a case type, you create a draft relationship between the object and
the case type. Visualization of this relationship helps your team understand what data objects they need to
define, so that users of your application can begin their Microjourney. For example, in a case type that
represents a hiring process, you can associate data objects for Personal details and Contact details with a
Collect personal details stage.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. In the Data & Interfaces section of a stage in which you want to add a data object, click Data, and
then select a data object that you want to use:
Choices Actions

a. In the list, select Data object New data object .

Create a new data b. In the New data object window, in the Name field, enter a descriptive
object name for the data object.
c. Click Submit.

Select an existing In the list, click Data object, and then select the data object that you want
data object to add.
By default, App Studio associates data objects with the Pega integration system.
3. Optional: To associate the data object with a different integration system, click the system name,
and then in the System section, in the Select system list, select a different system:
Choices Actions

a. In the list, select Create new.

Create a new b. In the New system dialog box, in the Name field, enter a descriptive name
system for the system. For example: Enter LinkedIn.
c. Click Submit.

Select an
In the list, select the system that you want to use.
existing system
4. Optional: To indicate that the application reads the data object from the system, select the Read
check box.
5. Optional: To indicate that the application updates the data object in the system, select the Write
check box.
Your application can both read and update data in the system.
6. Optional: To indicate that the external system that you want to use has defined APIs , in the System
details section, select the Existing API check box.
Using existing APIs affects project estimation and shortens the estimated development duration.
7. Optional: To communicate when you want to include the data object in your Microjourney, associate
the data object with a release:
a. In the Additional details section, click Configure release.
b. In the Edit details dialog box, in the Release list, select the release.
c. Optional: To indicate how much time the development team needs to implement the data
object, in the Complexity list, select a relevant option.

Implementing a data object includes defining fields in the data object, defining the system,
defining the data view that the use case requires, and defining a case type to include the data
object in an assignment or other type of step.

The complexity of the data object affects project estimation and expected development duration.
d. Optional: To provide more information, in the Comment text box, enter a short description.
e. When you implement the data object, select the Mark as done check box.
 f. Click OK.
8. To add more systems to the data object, in the Data & Interfaces section, locate the data object that
you want to associate with another system, click System, and then define the system details:
Choices Actions

a. In the list, select New system.

b. In the New system dialog box, in the Name field, enter a descriptive name for
Create a new
the system. For example: Enter Job opportunities.
system
c. Click Submit.
d. Repeat steps 4 through 7.

Add an
a. In the list, select the system that you want to use.
existing
b. Repeat steps 4 through 7.
system
9. Click Save.

Result: Your case life cycle displays draft data objects that you can use when you plan development of
your application.What to do next: Turn the draft data associations into permanent data objects that you
can use in your application. See Implementing draft data objects.

Integration systems

Implementing draft data objects

Provide data that is necessary to process your business cases and meet your goals by implementing draft
data objects. When you plan your Microjourney, you can associate draft data objects with case types. By
turning these data objects into permanent elements, you ensure that your customers can process the
Microjourney successfully.

Before you begin: Create draft data objects that visualize information that your Microjourney requires.
See Associating data objects with case types.

1. In the navigation pane of App Studio, click Data.

2. Click Data objects and integrations .
3. Click a draft data object that you want to persist.
Draft data object names have (Draft) appended to a descriptive name, for example Personal details (Draft).
4. In the Data model section, click Create data model.
5. In the Create new data model field, enter the name for the type of information that you want to
model.
6. In the Define source data field, define a location for your data by selecting one of the following
options:
To set a local Pega data object, select Now, and then select Pega in the Systems list.

By connecting to Pega database storage, you can add fields and complete your data model. When
your data model is complete, and your external data sources are available, you can optionally
connect to them too.

To define a source system later, for example if your source system is not yet ready, select Later.
7. Click Submit.

What to do next:

To prioritize work and start implementing draft relationships defined during planning your Microjourney,
analyze your application inventory. See Managing application inventory.

To provide meaningful information for your data object, define fields. See Defining the fields in a data
object.

Data modeling

Associating attachment categories with case types

To ensure that the workers who process your Microjourney have the relevant information, associate
attachment categories with your case type. Visualizing the attachments required by your Microjourney
helps you to gain a better overview of the information that your application users need to deliver. You can
also communicate to your stakeholders what documents or other attachments are crucial in the
Microjourney.

For example, in a hiring process, you can indicate that a job applicant provides scanned documents, for
example letters of recommendations and files CVs.
When you add an attachment category to your case life cycle, you create a draft relationship between the
attachment category and the case type. Draft relationships affect project estimation and clearly visualize
which application elements you need to implement, and as a result, help you to plan your application
development.

1. In the navigation pane of App Studio, click Case types, and then click the case type that you want to
open.
2. In the Data & Interfaces section, click Data Attachment , and then define the attachment
category:
Choices Actions

Use an existing
attachment Select the attachment category from the list of categories.
category

a. Click New attachment category.

Create a new b. In the New attachment category dialog box, in the Name field, provide a
attachment descriptive name for the attachment category. For example: Enter Letters of
category recommendation.
c. Click Submit.
3. To add more categories for the attachment, click Category, and then repeat step 2.
For example, you might need more attachment categories when you need a document in a printed
version and as a digital file.
4. Optional: To communicate when you want to include the attachment in your Microjourney, associate
the attachment category with a release:
a. In the Additional details section, click Configure release.
b. In the Edit details dialog box, in the Release list, select the release.
c. Optional: To indicate how much time the development team needs to implement the
attachment, in the Complexity list, select a relevant option.

Implementing an attachment category includes defining storage options and editing the case life
cycle to include the attachment in an assignment or other step type.

The attachment category complexity affects project estimation and expected development
duration.
d. Optional: To provide more information, in the Comment text box, enter a short description.
e. When you implement the attachment category, select the Mark as done check box.
f. Click OK.
5. Optional: To change the attachment category, in the Category properties pane, in the Select
category list, select a different category.
6. Click Save.

Attaching content to a case type

Attaching screen captures to a case

Managing application inventory

Plan the development of your application, manage the workload in your team, and prioritize your work
accordingly by following the application backlog on your Inventory landing page. The Inventory landing
page lists features, personas, and draft data associations across your Microjourney, so that your team can
map items to specific releases.

By analyzing the application inventory, you can also determine how different elements of your application,
such as personas and case types, interact with each other.

You associate personas and data objects with case types when you plan your Microjourney. By making
these associations, you can clearly visualize the data and participants that your business processes require.
After you create these associations, or draft relationships, you can analyze your application inventory, so
that you can prioritize work by checking releases associated with personas and data objects. You can also
group and filter personas and data objects for a better understanding of how these elements are related.
For more detailed planning, on the Inventory page, you can also manage your application features. For
example, you can associate a feature with a release, so that you can estimate your work more accurately.

Before you begin: Define the main elements of your application:

Create a case type, and then define the case life cycle by adding stages, processes, and steps. See
Adding case types to organize work.
Create personas that represent users of your application. See Adding personas to organize users.
Create data objects that visualize the information that your cases require to reach the resolution
stage. See Adding data objects to organize data.
Create features that represent usable functionalities in your application. See Creating features.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Inventory section, select the items of information that you want to view:
To manage draft personas, click Personas.
To manage draft data objects, click Data.
To manage application features, click Features.
4. Organize the list of items to display only the information that you need:
To group items, click Group, and then select the grouping method that you want to apply, for
example Complexity.
To display only selected information about items, click Fields, and then select the fields that you
want to display, for example Channel and Status.
To change how the information is displayed, click Density, and then select a format that you
want to apply, for example Compact.
5. Update the information to reflect the latest changes that you make in your application by clicking
More Edit details , and then performing the following actions in the Edit details window:
To change the iteration of your application in which you want to implement the item, in the
Release list, select a release.
To change the amount of time that the development team needs to implement the item, in the
Complexity list, select a new value.
To provide more information about an item, such as business value, in the Comment text box,
enter some additional description.
To mark the item as implemented, select the Mark as done check box.
6. Click Submit.

Adding features to application inventory

Get a quick overview of the functionalities that your development team needs to implement by adding
features to your application inventory. When you analyze your application inventory, you can
conveniently plan your application development in a more detailed way.

Creating a team
Configuring your dashboard

Adding features to application inventory

Get a quick overview of the functionalities that your development team needs to implement by adding
features to your application inventory. When you analyze your application inventory, you can conveniently
plan your application development in a more detailed way.

For example, you can create features that represent language packs and case types to ensure that you
deliver an application that meets the requirements defined with your stakeholders. During application
development, your team then turns features into usable functionalities.
Before you begin: To reuse features, add built-on applications to your current application. For more
information, see Adding built-on applications.

You can assign each feature a complexity level. Complexity indicates the time and effort that a team needs
to implement a feature and impacts further estimation of the time required for application development.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Inventory section, click Feature map.
 4. Add a feature to your application:
Choices Actions

a. Hover over the features list, and then click Add Add from existing features .
You can only add top-level features without any subfeatures.
b. In the Add from existing features dialog box, in the Feature list, select a
feature to reuse.
c. In the Release list, associate the feature with the iteration of your application.
d. Optional: To modify the feature for your current application, in the Complexity
list, select an option that indicates how much time a development team needs to
implement the feature.
Reuse a
Feature complexity impacts estimation of project completion time. Complex
feature
features elongate the estimated application development process.
from a
e. Optional: To provide more information about the feature, in the Comment text
built-on
box, enter some additional description. For example: Enter text that describes
application
the business value of this feature and provides an overview of what users can do
when the development team implements the feature.
f. Optional: To communicate that the feature is ready, select the Mark as done
check box.
Features that you mark as done have no impact on development time estimations.
g. To add more features, click Submit & add another, and then repeat steps 4.b
through 4.f.
h. Click Submit.

a. Hover over the features list, and then click Add Add new feature .
b. In the Add new feature dialog box, in the Name field, enter some text that
uniquely identifies the feature.
c. Optional: To associate the feature with the iteration of your application, in the
Release list, select a release.
d. To indicate how much time a development team needs to implement the feature,
in the Complexity list, select a relevant option.
Feature complexity impacts estimation of project completion time. Complex
Create a features elongate the estimated application development process.
new e. Optional: To provide more information about the feature, in the Comment text
feature box, enter some additional description. For example: Enter text that describes
the business value of this feature and provides an overview of what users can do
when the development team implements the feature.
f. Optional: To communicate that the feature is ready, select the Mark as done
check box.
Features that you mark as done have no impact on development time estimations.
g. To add more features, click Submit & add another, and then repeat steps 4.b
through 4.f.
h. Click Submit.

What to do next: Calculate the time and effort that you need to deliver your application. For more
information, see Estimating application development.

Creating features
Creating subfeatures
Tracking feature-driven development

The Microjourney in the Pega Express methodology FAQ

Reach your business goals faster and with greater effect by understanding and implementing the Pega
Express methodology while planning your Microjourney.

What are the key elements of a Microjourney?

Your Microjourney includes the following key elements:

Case types that are reusable templates of your business processes

Personas that represent parties that interact with cases through channels
Data objects that you need in order to process a case
For example, if your business objective is to review job applications, you can create a Hire a candidate case
type, and then associate the following personas with the case type:

A job applicant that uses a Job Bot portal

A staffing consultant that uses an HR Connect portal
A hiring manager that uses a Case Manager portal

Data that you need to process a hiring case might include a candidate's personal details, education, and
work experience.

For a holistic understanding of your customers' needs, you can now visualize these three elements on one
screen when you design a case type in the Case Designer tool in App Studio. For more information, see
Creating a Microjourney for customer success.

What do I need to do to start planning my Microjourney?

To associate personas and data objects with case types, you need to update your application to support the
Pega Express methodology. When you open your existing application, a prompt to update your application
is displayed. When you create a new application, it already supports planning a Microjourney. For more
information about the update, see Application update scenarios for the Pega Express methodology.

Do I need to update my built-on applications first?

Yes, you need to update your built-on applications first if they include data objects that your current
application uses. If you update your built-on applications first, when you update your current application,
the current application only references the data objects from your built-on applications.

When you update your current application first, it creates the data objects that it uses from the built-on
applications. If you update your built-on applications later, it duplicates the data objects. As a result, when
you start by updating your built-on applications, you save time and resources.

Do I need to update UI Kit or PegaRULES built-on applications

as well?
No, because UI Kit and PegaRULES built-on applications do not include any data objects or personas.

How do I prepare for an update?

For an update, you need an unlocked ruleset or you need to enable branch development. Otherwise, you
get an error message about no unlocked rulesets or versions and the update fails. For more information,
see Organizing rules into rulesets and Setting branch development preferences.

Where can I find the Roles landing page in App Studio?

For greater clarity, two new landing pages replace the Roles landing page: Personas and Access. The
Personas page lists all the personas from your application, and the Access page contains a matrix that you
use to provide the personas with access to various web channel and pages.

Do the new landing pages affect my existing access

configurations?
No. The introduction of the Personas and Access landing pages has no impact on your existing access
configurations. After you update your current application, you can view the settings that your application
migrates from the Roles landing page.

Does the Personas landing page list all the roles from a
previous version of my application?
No, the Personas landing page lists only roles that interact with your application through a channel. When
creating personas during an update, your application ignores the development roles that have access to
Dev Studio, App Studio, Admin Studio, and Prediction Studio, such as administrator or author.

Does my application create personas for all access groups?

Yes, your application creates personas for all access groups without requiring access to the development
portals, such as Dev Studio.

What happens to my data types after an update?

After you update your application, your data types persist and change into data objects. If your framework
and implementation applications have data types with the same labels, and you enable branch
development, merge the branch to your framework app first before you upgrade your implementation app.
Otherwise, the system fails to create data objects for the implementation application.

When I create a new application, which elements of a

Microjourney does it include?
When you create a new application without built-on applications, your new application includes:

Two default personas, Users and Managers.

No data objects.
Four default releases.

When you create a new application with built-on applications, your new application includes:

Data objects that your applications references from built-on applicationss.

Personas that your application references from built-on applicationss. The included Personas are
specific to the current application.
Personas that your application creates from access groups in the built-on applications. Your application
ignores the access groups that have access to the development portals, such as Dev Studio.
Relationships between personas and web channels that your application references from the built-on
applications.
Four default releases.

For relevant training materials, see the Pega Express methodology module on Pega Academy.

Adding case types to organize work

Adding personas to organize users
Adding data objects to organize data
Data modeling

Designing applications for reuse and extension

Save time and speed up your application development process by designing your applications for reuse and
extension. When you create reusable elements, such as rules and classes, you can implement them again in
future projects, to make your work more efficient.

For example, if you create a rule that defines a service-level agreement, you can include this rule in any
future cases that you design. At the same time, you improve the flexibility of your projects because you can
select from specific elements that your current business project requires.

Naming conventions for records

Give informative and descriptive names to the records that you create in Pega Platform, such as rules
and data instances, to help you manage your resources and provide quick context for other
developers. As a result, you speed up application development and promote reuse across your
application.

Rules in Pega Platform applications

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

Provide the data necessary to process your cases by referencing information in the form of properties.
When you refer to a property, your application calls a specific piece of information, such as a customer
phone number or an address.

Managing relevant records and components

Save time during application development by reusing elements such as relevant records and
components.

Creating an activity

Automate a system task for which a more appropriate rule type is not available by creating an activity.
With activities, you define a sequential set of instructions, or steps, that the activity completes
automatically. Each step calls a method or supported rule type to perform the required processing.

Creating binary file rules

Enhance and customize your application by creating a binary file rule that stores a graphics file, such
as an image, or other non-text file. The binary file rule type provides the security, inheritance
versioning, and deployment benefits of rule resolution to a file.

Troubleshooting tools and techniques

Naming conventions for records

Give informative and descriptive names to the records that you create in Pega Platform, such as rules and
data instances, to help you manage your resources and provide quick context for other developers. As a
result, you speed up application development and promote reuse across your application.

For example, when you create a ruleset to store service-level agreement rules for an HR department in
your organization, name the ruleset SLAforHR so that other developers can understand the purpose of the
ruleset and avoid duplicating the record.

As you create new items in your application, it is important to implement consistent and logical labeling.
This approach makes it easier for members of an organization or a development team to perform the
following tasks:

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

Before creating a record, consider the following actions:

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

General guidelines for record naming conventions

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

Choose names that reflect the purpose of the record.

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

Limitations on name lengths for rule types and objects

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

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

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

Naming conventions for flow actions and assignments

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

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

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

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

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

Naming conventions for access groups

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

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

Naming conventions for data objects

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

For more information, see Creating a data object.

Naming conventions for database objects

Database objects include tables, views, indexes, and so on created in the Pega Platform database or other
databases that a Pega Platform application uses. In general, name database tables in accordance with the
location of the respective work or data class in the Customer Enterprise Class Structure (ECS). Names of
standard Pega Platform database tables begin with pr_, pc_, or pi_. Numerous use cases require creating your
own tables to supplement the standard tables. As a best practice, use the application/ruleset name as a
suffix, for example MyApp_, and to try to resemble the existing name. For example, name the work table
MyApp_work.

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

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

Work tables

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

The following example include sample work tables names:

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

Work history tables

Name work history tables by using the following format: LOB name_work_history_workpool name. Ensure that
abbreviations of line of business name and work pool name match the abbreviations in the Customer ECS.
For example, for ABCD line of business and Order Intake workpool, name the table abcd_work_history_orderintake.

Data tables

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

Name enterprise-wide data tables in the following format: ent_data_domain name. For example, for a Networks
domain, name the data table ent_data_networks.

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

Constraints

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

Naming conventions for files

For records that derive from Rule-File- class, select a name that uses only lowercase characters to avoid
confusion between systems which have case-sensitive file names systems which do not have case-sensitive
file names. Begin the names of files for related functions with a common prefix character so they appear
grouped together in listings.
Naming conventions for flows
Name flows by using a combination of a verb and a noun that clearly describes a purpose of the flow, for
example Submit an order.

For more information, see Case life cycle elements.

Naming conventions for functions

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

Naming conventions for HTML streams

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

Naming conventions for router activities

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

ToAgent Assign to agent entered in parameter.

ToCorrPartyRole Assign to correspondence party role.

Assign to operator designated as the manager of

ToCostCenterManager
the cost center.

Assign to the current operator's default work

ToDefaultWorkbasket
queue.

Assign to manager of the current operator's

ToOrgUnitManager
organization unit.

Assign to a list for someone to monitor the service

level. This is a placeholder activity for copying to
your ruleset and modifying to reference your own
ToOverallSLA
service level work queue. Invoke the standard
Work-.OverallSLA routing when the work object is
created.

Assign to designated operator responsible for

ToProblemFlowOperator
investigating flow issues.

Assign to the work queue specified as the

ToWorkbasket
parameter.

ToWorklist Assign to the operator specified as the parameter.

ToWorkParty Assign to the appropriate work party.

For more information, see Assigning tasks to users.

Naming conventions for service packages

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

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

The following list includes sample service package names:

LOANSSOAP
LOANSEJBV2
LOANSEMAIL
LOANHTTPA, LOANHTTPB, LOANHTTPC

For more information, see About Service Package data instances.

Naming conventions for work queues and work groups

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

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

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

Naming conventions for specific records

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

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

Naming conventions for other objects

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

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

For example, database view to retrieve employee data records has the name get_employee_data_vw.Note: Avoid
using the prefixes pwvb_ or pcv_, because the system uses these prefixes in standard tables.
 Rules in Pega Platform applications
Organizing rules into rulesets
Organizing rules into classes

Rules in Pega Platform applications

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

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

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

For relevant training materials, see the Creation and maintenance of rules module on Pega Academy.

Creating a rule

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

Organizing rules

For an improved management of your application, organize its building elements – rules – in a logical
and coherent way. You can group rules into rulesets and classes, so that you can conveniently reuse
them during application development. As a result, you reduce development time and costs.

Rule resolution

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

Changing the scope of rules

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

Checking out a rule

To avoid accidental rule changes or conflicts that might result from multiple developers working on
the same rule, perform a check out, so that you can lock the rule and safely make changes to it. By
checking a rule out before editing, you avoid unwanted rule changes, and as a result save time and
maintain a better quality application.

Restoring the earlier state of a rule

During application development, you can undo recent changes to a rule and replace the current rule
with a previous copy, even if another developer created the newer copies.

Exploring rules in your application

To ensure that your application includes all the features that your business process requires, explore
rules that define these features. By exploring rules before you define new elements of your app, you
can also avoid duplicating resources, and as a result, save time and development costs.

Delegating a rule or data type

To delegate a rule or data type to enable your business line to configure simple application logic
without involvement from IT, complete the following steps.
 Importing the legacy ruleset from the Resource Kit

Applications that require deprecated rules that are no longer included in the Pega Platform distribution
need to import those legacy rules from the Resource Kit.

Renaming classes or rulesets during an archive import

Use the Refactor on Import wizard to rename classes or rulesets in an archive as it is imported. This
allows you to integrate the imported structure into the existing hierarchy on your system. The Refactor
on Import wizard supports merging RuleSets developed by Pegasystems or others into your
PegaRULES database.

Omitting history snapshots for data types

To improve performance and manage your resources efficiently, you can choose not to take history
snapshots when you develop data types. Every time a value in a data type changes, before you
implement the change, the system takes a snapshot of the previous instance in case you need to
restore the data type to the previous state. With multiple changes, omitting the snapshot can save you
time and resources.

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

1. In the header of Dev Studio, click Create, and then select the record category and type that you want
to create. For example: To create a data transform, click Create Data Model Data Transform .
2. In the record configuration area of the Create form, provide a name for your record and define its key
parts:
a. In the Label field, enter a short description in the form of a sentence that describes the purpose
of the record.
As a best practice, use up to 30 characters. Pega Platform appends rule information to the rule
name you enter to create the fully-qualified name.
b. Optional: To manually set the name key part of your record to a value that is different from the
default, in the Identifier field, click Edit, and then update the name.
The default value of this field is To be determined. The system automatically populates this
field with a read-only value based on the sentence that you enter in the Label field. The system
ignores spaces and special characters.
If you manually change the Identifier value, the system no longer autopopulates this field after
you provide a new value in the Label field.
c. In the remaining fields, specify additional key parts for your record.
The number of key parts, types, and restrictions varies by record type. As a best practice, start
each key part with a letter and use only letters, numbers, and hyphens.
d. Optional: To include all other configuration options supported by this record type, click View
additional configuration options.
These options vary by record type and only appear for records that support Quick Create options.
By using the Quick Create option for certain rule types, you can create rules directly in the
Create dialog without having to open the rule form. Rule types with this option include
properties, field values, when conditions, flows, and activities.
3. In the Context section, if the Development branch list appears, select a branch in which to store
your record:
To create the record in a branched version of the ruleset, select a branch name.

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

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

The form displays the Development branch list when you define branches in the current application,
or in one of the built-on application layers.
4. Select an application layer in which you want to store the record.
You can only store records in application layers with access to the selected development
branch.Note: The Production Rulesets option appears as the first option in the stack if your current
access group has production rulesets defined. Choosing this option restricts the Add to ruleset field
only.
 5. In the Apply to field, select the class to which this record applies.

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

For example: Choose MyCo-LoanDiv-MortgageApplication rather than MyCo-LoanDiv-as the Apply to

class for a new flow or property, unless you are certain that the record is applicable to all the objects
in every class derived from MyCo-LoanDiv-.
Tip: To select a class name that is not a case or a data type, click the View all link.
6. In the Add to ruleset field, select the name of a ruleset to contain the record.
If the development branch is set to [No Branch] or you have no available branches to choose from, specify
a version for the specified ruleset name.
7. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
8. Click Create and open .

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

Copying a rule or data instance

Save time and speed up the development process of your application by promoting reuse of resources.
Instead of creating a new record that might be similar to a rule that already exists, copy an existing
rule and then make the necessary changes.

Setting rule status and availability

Searching for a rule
Configuring system settings

Copying a rule or data instance

Save time and speed up the development process of your application by promoting reuse of resources.
Instead of creating a new record that might be similar to a rule that already exists, copy an existing rule
and then make the necessary changes.

Consider a scenario in which you copy a service-level agreement rule that defines goals and deadlines for
customer service representatives (CSRs) to follow when CSRs review loan requests, and then change some
elements of the rule to adjust it to reviewing mortgage requests. For example, you can make the goal
longer.
Before you begin: You must have the @baseclass.ToolbarFull or @baseclass.ToolbarSaveAs privilege to
copy rules. The result of copying an existing rule is a new record with key parts that the system
prepopulates with the values of the original rule. To save the new record, you need to change at least one
key part. The key parts are an identifier, a branch that stores the record, a class that applies to the record,
a ruleset, and a ruleset version.Note: Because the Save As form displays a subset of the fields and
functionality that are specific to each data instance, some fields might vary between different rule types.

1. In the navigation pane of Dev Studio, navigate to the record that you want to copy. For example: To
copy a service-level agreement rule, click Records Process Service Level Agreement , as in the
following example:

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

Copying a rule in a locked ruleset

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

Copying a rule in an unlocked ruleset

4. Review the record label and identifier to determine which key parts you can change.
Consider the following factors:
If you plan to leave the context for this record unchanged, change the identifier.
If the record type that you want to copy has name restrictions, the Identifier field appears as not
editable.
 5. In the Context section, review the record context to determine what information about the storage of
the record in your application you can change.
Consider the following factors:
If you plan to leave the label and identifier unchanged, change at least one element of the
context of the record. You can change a branch that stores the record, a class that applies to the
record, a ruleset, and a ruleset version.
If you copy a rule with Final availability and leave the key parts unchanged, select the same
ruleset name and a higher version number. By default, you cannot override a Final rule with
another rule in a different ruleset.
When you copy a rule, you cannot define the rule availability. The system clears the rule
availability when the record identifier is unchanged, and the rule meets any of following
conditions:
the ruleset is unchanged
the class that applies to the record is unchanged
the original record is specialized by circumstance
For more information about rule availability, see Setting rule status and availability.
6. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
7. Click Create and open . Result: The rule form opens.

What to do next: Make the necessary changes and then save the rule form.

Organizing rules into rulesets

Organizing rules into classes
Rule resolution
Changing the scope of rules
Creating a rule specialized by circumstance
Troubleshooting newly created rules
Creating a rule

Organizing rules
For an improved management of your application, organize its building elements – rules – in a logical and
coherent way. You can group rules into rulesets and classes, so that you can conveniently reuse them
during application development. As a result, you reduce development time and costs.

Organizing rules into rulesets

To identify, store, and manage the set of rules that define the reusable elements of an application,
organize rules into rulesets. When you group rules into a ruleset, you save time, because you can
reuse an entire ruleset within different applications in your system instead of reusing or creating
individual rules.

Organizing rules into classes

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

Deleting a rule

Save disk space by deleting rules that are no longer relevant in your application. For example, during
application development, you create a field property to capture a phone number, but later you need to
capture multiple phone numbers. You create a list property, and then delete the field property. As a
result, you improve the extensibility and user understanding of your application by providing only the
rules that your application requires.

Organizing rules into rulesets

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

You identify each ruleset by name and version number. Each version number consists of the following
parts:

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

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

When you create a ruleset, you define whether the ruleset is locked or unlocked. By creating a locked
ruleset, you protect the ruleset from accidental changes because developers must enter a password before
editing the ruleset. You can also define passwords for other actions, such as adding a new ruleset version,
or updating the ruleset.

To allow members of your development team to work simultaneously on different features, create branch
rulesets that developers use as isolated sandboxes. As a result, you reduce the risk of overwriting work,
and improve the quality of your application.

Creating rulesets

Reduce development time and costs by creating rulesets. After you create a ruleset, you can group
rules, which are reusable elements of your application, together in a logical way in the ruleset. As a
result, you conveniently manage, maintain, and reuse your rules.

RuleSet Maintenance wizard

Manage reusable resources in your application in a convenient and intuitive way by performing
operations in the Ruleset Maintenance wizard. You can copy rulesets and ruleset versions into new
versions, merge several ruleset versions into a single version, move rules from one ruleset into
another, or change the version number for a ruleset. As a result, you save time and increase efficiency
of the development process.

Defining the security of a ruleset

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

Categorizing a ruleset

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

Deleting a ruleset

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

Creating applications
Application Structure landing page
Application Validation mode ruleset

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

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

Creating a ruleset and a ruleset version

For easier maintenance and development of your application, create rulesets so that you can
categorize the rules that your application uses based on usage, purpose, and dependencies. You can
also create newer versions of existing rulesets to keep track of version control. As a result, you can
quickly locate and analyze the elements that you change in your application.

Copying rulesets

To speed up application development, reuse resources by copying rulesets. For example, you can copy
a ruleset if you want to modify only some of the rules that the ruleset includes, to increase flexibility of
your application.

Viewing test coverage reports

Viewing test coverage reports
Viewing test coverage reports
Operators

Creating a ruleset and a ruleset version

For easier maintenance and development of your application, create rulesets so that you can categorize the
rules that your application uses based on usage, purpose, and dependencies. You can also create newer
versions of existing rulesets to keep track of version control. As a result, you can quickly locate and analyze
the elements that you change in your application.

For example, you can create a ruleset that stores APIs that your organization provides. When you want to
enhance the APIs, create a new ruleset version, so that you can track and manage the changes over time.

1. In the header of Dev Studio, click Create SysAdmin RuleSet .

2. Create a new ruleset or ruleset version:
To create a new ruleset, in the RuleSet Name field, enter a unique name for your ruleset.

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

To create a new ruleset version, in the RuleSet Name field, press the Down arrow key, and then
select the ruleset for which you want to create a new version.
Result: The system populates the version and description of your ruleset.
3. Optional: To change the version number of your ruleset, in the Version field, enter a new value. For
example: Enter 01-01-03.
By default, for a new ruleset version, the system enters 01-01-01 as the version number. For existing
rulesets, the system increments the highest version by one patch number. In a version number, the
two first digits correspond with the release, the middle digits correspond with the minor version or
enhancement, and the final digits correspond with the patch version.
 4. Optional: To change the description of your ruleset, in the Description field, enter a new value. For
example: Enter SampleRuleset:01-01-03
By default, the system forms the description by combining the ruleset name and version number.
5. Click Create and open .

What to do next: Configure version settings for your ruleset. For more information, see Configuring
ruleset version settings.

Configuring ruleset version settings

For improved management of your application, define the behavior of your ruleset and how it interacts
with other elements of your application by configuring ruleset version settings.

Rule check-in process

Creating branch rulesets

Configuring ruleset version settings

For improved management of your application, define the behavior of your ruleset and how it interacts with
other elements of your application by configuring ruleset version settings.

For example, you can lock a ruleset to keep it in its original state, or require development approval for
checking in rules into the ruleset, in order to track and manage changes.
Before you begin: Create a ruleset or a ruleset version. For more information, see Creating a ruleset and
a ruleset version.

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

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

Categorizing a ruleset
Deleting a ruleset
Organizing rules into classes
Moving rules

Copying rulesets
To speed up application development, reuse resources by copying rulesets. For example, you can copy a
ruleset if you want to modify only some of the rules that the ruleset includes, to increase flexibility of your
application.

For instance, if you create an application that processes loan requests and mortgage requests, you can
copy a ruleset that includes system-level agreement rules, and then modify specific rules to meet your
unique business needs.
When you copy a ruleset, the system copies the ruleset versions, security, category, and history settings.

1. In the header of Dev Studio, click Configure Application Structure RuleSet Stack .
 2. On the RuleSet Stack tab, in the Current Application section, click the ruleset that you want to
copy.
3. In the header of the Edit Ruleset form, click the Down arrow next on the Save button, and then click
Save as.
4. Optional: To provide additional information about the ruleset, in the Short description field, modify
the default description.
5. In the RuleSet Name field, enter a new, unique ruleset name.
6. Optional: To change the version number of your ruleset, in the Version field, enter a new value. For
example: Enter 01-01-03.
By default, for a new ruleset version, the system enters 01-01-01 as the version number. For existing
rulesets, the system increments the highest version by one patch number. In a version number, the
two first digits correspond with the release, the middle digits correspond with the minor version or
enhancement, and the final digits correspond with the patch version.
7. Optional: To change the description of your ruleset, in the Description field, enter a new value. For
example: Enter SampleRuleset:01-01-03
By default, the system forms the description by combining the ruleset name and version number.
8. Click Create and open .

What to do next: Modify the copied ruleset:

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

Changing the scope of rules

Deleting a ruleset

RuleSet Maintenance wizard

Manage reusable resources in your application in a convenient and intuitive way by performing operations
in the Ruleset Maintenance wizard. You can copy rulesets and ruleset versions into new versions, merge
several ruleset versions into a single version, move rules from one ruleset into another, or change the
version number for a ruleset. As a result, you save time and increase efficiency of the development
process.

Before you begin working in the RuleSet Maintenance wizard, consider the following information:

Moving a ruleset
Copying or moving a ruleset version
Merging rulesets and ruleset versions
Changing a ruleset version number
Rule conflicts
Locked ruleset versions
Checked-out rules
Prerequisites and preparation
Recovering merged rulesets
Logging

The available operations for this wizard depend on the Pega-RuleRefactoring agents . If you use this wizard,
confirm that the Pega-RuleRefactoring agents are enabled on at least one node in your system.

Moving a ruleset
When you move a ruleset, the wizard processes the source rules in each ruleset version in the ruleset and
any non-versioned rules that are associated with the ruleset. The wizard updates the ruleset name and the
ruleset version of each rule to the values that you specify as the target. As a result, the wizard deletes the
source ruleset and copies the rules into the target ruleset. The values of the pzInsKey of the rules remain
unchanged.

The way in which the wizard handles multiple ruleset versions in the ruleset depends on whether you
specify a target version:

If you move a ruleset without specifying a target version, the wizard keeps the same structure and
contents of the source ruleset versions under the target ruleset.
 If you move a ruleset and specify a target version, the wizard merges ruleset versions in the source
ruleset by skimming the rules to the specified version under the target ruleset. As a result, the wizard
moves the highest-versioned instance of each rule in the source ruleset versions to the target ruleset
and specified ruleset version.

For example, if you move a ruleset that contains rules with ruleset versions 01-01-01, 01-01-02, and 01-01-
03 into a new target ruleset and specify a version of 01-02-01, the target ruleset version contains the
highest version of all the source rules that versions 01-01-01, 01-01-02, and 01-01-03 contain. The wizard
omits lower-versioned duplicates. In this example, if both 01-01-01 and 01-01-02 ruleset versions contain a
duplicated rule, the wizard moves the rule from 01-01-02 to the new ruleset name with ruleset version 01-
02-01, and omits the duplicate rule in 01-01-01.

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

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

You cannot copy a ruleset.

Copying or moving a ruleset version

When you copy a ruleset version, the original source ruleset version remains unchanged. Each target rule
that the wizard creates is identical to the original source rule with the following exceptions:

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

Moving a ruleset version changes the source rules. The wizard updates the ruleset version of each rule to
the values that you specify as the target. The wizard deletes the rule from its source ruleset version, and
copies the rule into the target ruleset version. The value of the pzInsKey of the rule remains unchanged.

Before you copy or move a ruleset, ensure that you unlock and check in the target ruleset.

Merging rulesets and ruleset versions

You can merge multiple source ruleset versions that belong to the same or different rulesets. For example,
you can skim the ruleset by collecting only the highest version of every rule in the ruleset versions into the
target, or you can compress the rulesets down to a lower level. You control the merge by specifying the
target version and the order in which the wizard processes ruleset versions.

When you select the ruleset versions, you establish the order of precedence by listing the ruleset versions
in the wizard interface. The wizard processes the rules in the order, from top to bottom, collects the first
version of every rule that the wizard finds, and omits any duplicate rules. The wizard processes rules in the
following order:

The wizard first processes rules from the first ruleset version that you list, and then discards duplicate
rules in the following versions in the list.
Then the wizard processes any remaining rules in the second ruleset version in the list, and omits any
rules that are duplicates of the rules for which the processing is complete.
The wizard continues to process rules in the same way down the list of versions.

Note: When you compress rulesets with prerequisites, begin with the ruleset that contains the fewest
dependencies. For example, if ruleset A requires ruleset B as a prerequisite, and ruleset B requires ruleset
C as a prerequisite, then first compress the ruleset A, then B, and finally C. If you compress the rulesets in
the order C, B, and A, you risk losing some rules that you expected to retain.

When you merge rulesets or ruleset versions, you can delete the sources when the merge is complete.
However, if you merge ruleset versions and opt to delete the sources, the source versions are deleted, but
not their rulesets.

When you merge ruleset versions, you can also exclude categories of non-versioned rules.

Note: When you select Libraries and Functions from the list of non-versioned rules, the wizard merges all
functions are merged when the ruleset name changes. When the ruleset name is the same and only the
version changes, the wizard treats functions as versioned rules and only merges the patch functions.

Changing a ruleset version number

You can change the version number for a particular ruleset version, no matter if the version number that
you designate already exists. The target version belongs to the same ruleset as the source version. All
rules, including non-resolved rules, from the source ruleset version become part of the target version. All
rules retain their original pzInsKey values, and therefore retain their history.

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

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

Locked ruleset versions

The wizard only changes rules that belong to unlocked ruleset versions. If a ruleset version that you want
to change by the wizard operation is locked, the wizard prompts you for the password to unlock the version
before continuing with the operation. To copy a ruleset version, ensure that you first unlock the target
rules. You can lock the source rules because the copy operation leaves the target rules unchanged. To
move a ruleset or ruleset version, ensure that you unlock both the source and target rules.

For more information about locking rulesets, see Defining the security of a ruleset.

Checked-out rules
As a best practice, ensure that you check in all rules are checked in before you move or copy a ruleset or
ruleset version.

If the wizard encounters checked out rules, the wizard displays a warning page and provides a report of the
checked out rules. From the report window you can open the rules and check in the rules for which you
have permission, or save a list of the rules in a spreadsheet. If you exit the wizard to check in rules, you
must restart the wizard from the beginning.

For more information about rule check in, see Checking in a rule.

Prerequisites and preparation

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

Back up your Pega Platform system before you run operations in the wizard.
You can only copy or move rulesets or ruleset versions that are in your ruleset list.
Ensure that you unlock and check in rules that you want to modify. You receive warning if the wizard
encounters any locked or checked out rules during a copy or move operation, but as a best practice
unlock and check out the rules before you start the wizard.

When you work with ruleset versions, you can copy any prerequisite rulesets that the target ruleset version
requires.

Recovering merged rulesets

Before merging the rulesets, the wizard creates a backup of each rule named Bkup_SourceRuleSet.zip and
Bkup_TargetRuleSet.zip. You can optionally use the files to recover the original rulesets.

Logging
Each operation of the wizard creates an instance of the Log-Merge-RuleSet class, that includes error
messages or other information. The key for this instance is the date and time of the start of the wizard.

Class rules do not have a version. Do not delete Class rules if any version of the ruleset remains in use.

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

Copying ruleset versions in a RuleSet Maintenance wizard

Promote reuse of resources across your application to save time and make your development process
more efficient by copying ruleset versions. Instead of creating new elements of your application, you
can copy existing rules so that you perform necessary modifications and implement existing
functionality for your business requirements.

Merging rulesets and ruleset versions in a RuleSet Maintenance wizard

Increase efficiency and speed up your application development by merging rulesets and ruleset
versions. As a result, you make managing the resources in your system more convenient.

RuleSet Maintenance wizard step 3

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

RuleSet Maintenance — Locked Rules

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

RuleSet Maintenance — Checked-Out Rules

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

Copying ruleset versions in a RuleSet Maintenance wizard

Promote reuse of resources across your application to save time and make your development process more
efficient by copying ruleset versions. Instead of creating new elements of your application, you can copy
existing rules so that you perform necessary modifications and implement existing functionality for your
business requirements.

For example, you can copy a ruleset version that includes service-level agreement rules for an HR
department in your organization. You can then modify parts of the rules to apply to the Engineering
department.
Before you begin: Unlock and check in a target ruleset version for which you want to copy the rules. For
more information, see Defining the security of a ruleset and Checking in a rule.

1. In the header of Dev Studio, click Configure System Refactor RuleSets .

2. On the Rulesets tab, in the Refactor Rulesets Utilities list, click Copy/Merge RuleSet.
3. In the RueSet Maintenance section, in the list of options, select Copy.
4. Specify the type of resources that you want to copy by selecting RuleSet Versions.
You cannot copy an entire ruleset.
5. In the Available Source RuleSet(s) list, select ruleset versions that you want to copy, and then click
Move.
 Tip: To move all ruleset versions, click Move all.
6. Optional: To specify the order in which the wizard processes ruleset versions, in the Order of
precedence during Copy/Merge list, reorder the ruleset versions by clicking the Move up and
Move down buttons.
If you work with multiple ruleset versions, the wizard processes ruleset versions in the order from top
to bottom of the list. As a result, the wizard processes rules from the top of the list first are first and
omits duplicate rules in the following versions in the list. Then the wizard processes any remaining
rules in the second ruleset version in the list and omits duplicates in the following versions. The wizard
then continues to process ruleset versions in the same way until the end of the list.
7. In the Target section, in the Target RuleSet Information column, provide information about the
target ruleset:
a. In the Name field, enter the name of the target ruleset.
b. In the Version field, enter the version of the tagret ruleset.
Tip: You can use existing values or create a new ruleset and a ruleset version.
8. In the Target section, specify how you want the wizard to behave if both source and target rulesets
include rules with the same names:
To overwrite target ruleset instances with the source ruleset instances, select Yes.
To omit processing of source rules that duplicate existing target rules and leave the target rules
unchanged, select No.
For example: The following figure shows a sample configuration for copying ruleset versions:

Copying ruleset versions

9. Optional: To copy rulesets with ruleset prerequisites, select the Copy missing Ruleset
 Prerequisities check box.
10. Click Next.
11. In the RuleSet Maintenance section, analyze information about source and target rulesets for the
copy operation.
12. To run the operation in the background, in the Run as a background process? row, selectYes.
Copying ruleset versions as a background process saves time when the source ruleset versions
contain a significant number of rules. If you have an email account configured in Pega Platform, you
receive an email when the process is complete.
13. Click Copy.
14. When the copying is complete, in the RuleSet Maintenance section, review the results of the
operation.
15. Optional: To review a detailed list of copied rules, click Click here to view list of Processed
Rules.
a. Optional: To share the list of rulesets with other developers or to review the list offline, in the
DisplayRulesProcessed window, click Export Page to Excel, and then close the window.
16. Click Done.

Merging rulesets and ruleset versions in a RuleSet Maintenance

wizard
Increase efficiency and speed up your application development by merging rulesets and ruleset versions.
As a result, you make managing the resources in your system more convenient.

For example, if you have multiple rulesets with rules that define user interface of your application, you can
merge the ruleset to have all the UI elements in one place.
Before you begin: Unlock and check in rules that you want to merge and a target ruleset version where
you want to save the rules. For more information, see Defining the security of a ruleset and Checking in a
rule.

1. In the header of Dev Studio, click Configure System Refactor RuleSets .

2. On the Rulesets tab, in the Refactor Rulesets Utilities list, click Copy/Merge RuleSet.
3. In the RueSet Maintenance section, in the list of options, select Merge Source RuleSet(s) to
Target RuleSet.
4. Specify the type of resources that you want to merge:
To merge rulesets, select Entire RuleSets .
To merge ruleset versions, select RuleSet Versions.
5. In the Available Source RuleSet(s) list, select rulesets or ruleset versions that you want to merge,
and then click Move.
Tip: To move all rulesets or ruleset versions, click Move all.
6. Optional: To specify the order in which the wizard processes ruleset versions, in the Order of
precedence during Copy/Merge list, reorder the ruleset versions by clicking the Move up and
Move down buttons.
If you work with multiple ruleset versions, the wizard processes ruleset versions in the order from top
to bottom of the list. As a result, the wizard processes rules from the top of the list first and omits
duplicate rules in the following versions in the list. Then the wizard processes any remaining rules in
the second ruleset version in the list and omits duplicates in the following versions. The wizard
continues to process rules in the same way until the end of list.
7. In the Target section, in the Target RuleSet Information column, provide information about the
target ruleset:
a. In the Name field, enter the name of the target ruleset.
b. If you merge ruleset versions, in the Version field, enter the version of the tagret ruleset.
Tip: You can use existing values or create a new ruleset and a ruleset version.
8. In the Target section, specify how you want the wizard to behave after the merge is complete:
To delete the source rulesets, select Yes.
To keep the source rulesets, select No.
For example: The following figure shows a sample configuration when copying ruleset versions:

Merging rulesets
 9. Optional: If you merge ruleset versions, to copy rulesets with ruleset prerequisites, select the Copy
missing Ruleset Prerequisities check box.
10. Optional: If you merge ruleset versions, to exclude non-versioned rules from the merge operation, in
the Which non-versioned rules do you want to modify? section, in the Type list, clear the check
boxes of the rule types that you want to omit.
Note: When you select Libraries and Functions from the list of non-versioned rules, the wizard
merges all functions when the ruleset name changes. When the ruleset name is the same and only the
version changes, the wizard treats the functions as versioned rules.
11. Click Next.
12. In the RuleSet Maintenance section, analyze information about source and target rulesets for the
merge operation.
13. To run the operation in the background, in the Run as a background process? row, selectYes.
Merging rulesets and ruleset versions as a background process saves you time when the source
ruleset versions contain a significant number of rules. If you have an email account configured in Pega
Platform, you receive an email when the process is complete.
14. Click Merge.
15. When the copying is complete, in the RuleSet Maintenance section, review the results of the
operation.
16. Optional: To review a detailed list of copied rules, click Click here to view list of Processed
Rules.
a. Optional: To share the list of rulesets with other developers or to review the list offline, in the
DisplayRulesProcessed window, click Export Page to Excel, and then close the window.
17. Click Done.

RuleSet Maintenance wizard step 3

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

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

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

rules processed
data instances processed
rules in conflict
processing errors

If there were no data instances to process, errors, or conflicting rules, the corresponding links do not
appear.

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

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

About the RuleSet Maintenance wizard

RuleSet Maintenance — Locked Rules

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

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

About the RuleSet Maintenance wizard

RuleSet Maintenance — Checked-Out Rules

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

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

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

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

About the RuleSet Maintenance wizard

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

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

Update a ruleset or update class rules in a ruleset.

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

1. In the Records explorer of Dev Studio, click SysAdmin RuleSet , and click a rule to open it.
2. Click the Security tab.
3. If you defined a password that a user must match to update the ruleset, in the Enter password
values section, in the To update this RuleSet field, enter the password to unlock the ruleset.
4. To indicate that this ruleset contains rules that tailor, override, and extend an application, rather than
define an application, in the Rule management section, complete the following fields:
a. To specify that a ruleset is not intended to be moved to other Pega Platform systems, select
Local customization?.
This setting is advisory only and does not affect the ruleset functionality.Note: If you select this
option, do not select Use check-out?.
b. To enable developers to check out this ruleset when updating it, select Use check-out?.
As a best practice, select this option to avoid the risk of multiple developers updating a ruleset
and overwriting each other's changes.
c. Optional: To use a flow rule to manage development and check-in on this ruleset, in the Work
class used for approval process field, enter the work type to which the flow rule that controls
check-ins applies.
Note: Leave this field blank if you did not select Use check-out? in step 4.b. The Work class
used for approval process field supports advanced rule management features, which are
useful when a large development team is involved or when a development leader wants to
review each change made by others on the development team before the rule is checked in.For
more information about checking in rulesets, see Configuring the rule check-in approval process.
d. Optional: In the Work flow to use for approvals field, enter the name of the flow rule that
controls rule check-in for this ruleset.
Note: Leave this field blank if you did not select Use check-out? in step 4.b. The Work flow to
use for approvals field supports advanced rule management features, which are useful when a
large development team is involved or when a development leader wants to review each change
made by others on the development team before the rule is checked in.
5. Optional: Use the Define passwords section to prohibit users from adding or updating versions of
this ruleset, or updating this ruleset.
Lock the setting by entering passwords in the following fields. When you save the rule, the field is
replaced by a check box. If you leave a field blank, no password is required.
a. In the To Add a Ruleset Version field, enter a password that the user must match before
creating (beneath the version array) or copying a version for this ruleset on the Versions tab.
b. In the To Update a Ruleset Version field, enter a password that the user must match before
updating a version on the Versions tab.
c. In the To Update this Ruleset field, enter a password that a user must match when updating
this ruleset. This restriction includes updates to the versions on the Versions tab.
Note: To unlock the To Add a Ruleset Version and To Update a Ruleset Version settings,
clear the check box and save the rule.

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

6. Click Save.

Deleting a ruleset
Organizing rules into rulesets

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

In most cases, accept the default Standard ruleset type.

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

1. In the Records explorer of Dev Studio, click SysAdmin RuleSet , and click a rule to open it.
2. Click the Category tab.
3. In the RuleSet Type field, select the category to which this ruleset belongs.
Your selection affects where this ruleset appears in a requestor's ruleset list, and how rule resolution
finds the rules in the ruleset.
Standard – A "normal" ruleset that can contain all types of rules.Note: All rulesets created in
Pega Platform 5.3 and earlier belong to this category.
Component – A restricted ruleset designed to encapsulate functional or capabilities that operate
only on embedded pages. Rules in a component ruleset are designed and intended for reuse in
multiple systems and applications.
Shared – A restricted ruleset designed for reuse that operates on top-level pages only. See
shared ruleset for the restrictions.
Caution: Choose this value carefully. Although you can change ruleset types other than Override
later, Pega Platform does not then check whether existing rules in the ruleset meet the restrictions of
the Shared or Component categories.
4. If you chose the Component rule type in step 3, the Property to embed in application section
displays. To establish communication between Pega Platform and a component application, complete
the following fields:
a. In the Recommended Name field, enter a Page -mode property that is made available to both
the primary (calling) application and the component ruleset.
This provides communication between the primary application and the component application.
b. In the Page Name field, enter a clipboard page name that the component can access to pass
values to and from the calling application.
c. In the Page Description field, enter a description for the clipboard page.
d. Click Add a row to add additional properties.
5. Optional: To add test case rules to the ruleset, in the Test automation settings section, select Use
this ruleset to store test cases.
For more information, see Creating unit test cases for rules.
6. Click Save.

Deleting a ruleset
Organizing rules into rulesets

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

Before you begin:

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

Review access groups to confirm that they do not reference application rules to be deleted or the
ruleset version to be deleted.

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

Review listener data instances (such as Data-Admin-Connect-EmailListener ) to confirm that they do

not reference service rules that will be deleted.

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

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

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

1. In the header of Dev Studio, click Configure > System >Refactor > RuleSets > Delete a RuleSet
to start the tool.
2. Select the ruleset to be deleted in the Original RuleSet field.
3. Optional: Select a ruleset version to be deleted in the RuleSet Version field.
4. Click the Delete button to begin processing. This may take several minutes. Result: The system
creates a backup of the ruleset in PRPC's explicit temporary directory. A status area shows progress
and the results of the operation.
5. If errors occur, click the Total Number of Errors link in the lower right corner of the display form to see
any error messages. This list can't easily be accessed after you close the form; print the list so you can
research and address the errors.
6. Click Close.

Result:

The system saves the deleted ruleset in a file called "RuleSetName_RuleSetVersion_DELETE.zip" in PRPC's
temporary directory.

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

RuleSet Maintenance wizard

Distributing applications between systems
Organizing rules into rulesets

Organizing rules into classes

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

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

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

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

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

Understanding class layers

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

Understanding class hierarchy and inheritance

To save development time when creating an application, reuse rules by organizing them into classes,
and then creating dependencies between the classes. When you create a class hierarchy you define
which classes contain other classes, and as a result, you define how classes reuse or inherit rules.
 Understanding external classes

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

Creating classes

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

General tab on the Class form

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

Locking tab on the Class form

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

Advanced tab on the Class form

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

External Mapping tab on the Class form

The External Mapping tab is used primarily for external classes. External classes are created by the
Connecotr and Metadata wizard or the Database Class Mappings gadget and are linked by a Database
Table data instance to a table in a database other than the PegaRULES database.

About the Rename a Class wizard

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

About the Delete a Class wizard

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

Understanding class hierarchy and inheritance

Understanding class layers

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

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

For example, an enterprise that makes auto loans has an auto loan framework application that contains all
of the assets needed for the basic auto loan process. The enterprise then develops two implementation
applications built on the auto loan framework to meet the specific requirements of its two divisions: a
commercial business line and a personal line.
Using the New Application wizard, you can build a new implementation application and its implementation
classes on an existing framework application. You can reuse some or all of the case types and data types of
the framework application. In your new implementation application, you can use the Dev Studio landing
pages, explorers, rule forms, and reports to reuse many of the rules and data objects inherited from the
built-on framework layer. For example, while developing a process, you can select specifications or
processes in a framework ruleset for reuse or customization in the current application.

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

Implementation classes
Implementation classes define the extension, reuse, and specialization of assets in a framework layer to
meet the business requirements of an organization, division, or organizational unit. For example, you can
build two division-level implementations – business auto loan and personal auto loan – on an organization's
auto loan framework layer.

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

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

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

Organization classes belong to the organizational layer. In most configurations, your implementation and
framework layers inherit by pattern inheritance from organization classes.

Configuring applications for reuse

Creating applications
Creating applications

Understanding class hierarchy and inheritance

To save development time when creating an application, reuse rules by organizing them into classes, and
then creating dependencies between the classes. When you create a class hierarchy you define which
classes contain other classes, and as a result, you define how classes reuse or inherit rules.

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

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

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

Class naming convention

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

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

Class inheritance
Classes can inherit rules in the following ways:

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

Creating rulesets
Creating branch rulesets
Categorizing a ruleset

Understanding external classes

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

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

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

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

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

External classes do not contain the @baseclass.pzInsKey and @baseclass.pxObjClass properties, which are
present in every internal class. In some cases, no single property in the external class can serve as a
unique handle. To support the Obj-Open-by-Handle method with external classes, Pega Platform assembles
a substitute string from the key columns of the table.

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

System messages sometimes refer to external classes as "Obj-External"; however, Pega Platform does not
have an Obj-External method.

Creating classes
Organizing rules into rulesets

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

1. In the header of Dev Studio, click Create SysAdmin Class .

2. In the Class record configuration section, in the Label field, enter a short description for the class
that you want to create.
3. In the Class name field, enter a unique name for your class.

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

To show the relationship between classes, use a hyphen in the class name in which the first name is a
parent class.
For example: To create a Jobtitles class that derives from an HR class, enter HR-Jobtitles.
Note: Avoid using names that start with Code-, System-, and History-, because the system creates these
classes automatically.
4. In the Context section, select an application layer in which to store your class.
5. In the Add to ruleset list, select a ruleset in which to store your class.
6. Optional: To override the default work item that your application associates with this class, in the
Work item to associate field, press the Down arrow key, and then select a work item.
For more information about default work items, see Setting your current work item.
7. Click Create and open .
8. On the General tab of the class form, select a class type, and then define the class settings for your
new class:
Choices Actions

a. In the Select class type list, select Abstract.

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

a. In the Select class type list, select Concrete.

b. In the Settings section, in the Created in version field, enter the
Define the settings
ruleset version that applies to this class, and then go to step 9.
for a concrete class
Concrete classes have instances in a database. For more information,
see Class keys.
9. Define the class group settings of a concrete class:
Choices Actions

a. In the This class list, select The class is a class group. Result: The
Class group field autopopulates with the class name.
b. Optional: To encrypt the Storage Stream of each instance of this
concrete class when saved to the PegaRULES database, and to decrypt
the Storage Stream when an instance is retrieved from the database,
select the Encrypt BLOB check box.
Create a class For more information, see Encrypting the storage stream (BLOB).
group c. Optional: To define key parts of the class, in the Keys section, provide a
key name and a caption.
 Choices For more informationActions
about class keys, see Class keys.
d. Optional: If you provide only one key, to ensure that instances of this
class are unique, and to automatically supply a globally unique value for
further new instances, select the Automatically generate a unique ID
for records of this type check box.

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

a. In the This class list, select belongs to a class group.

b. In the Class group field, enter a class group name that you want to
Define the settings include this class.
for a class that c. Optional: To encrypt the Storage Stream of each instance of this
belongs to a class concrete class when saved to the PegaRULES database, and to decrypt
group the Storage Stream when an instance is retrieved from the database,
select the Encrypt BLOB check box.
For more information, see Encrypting the storage stream (BLOB).
10. In the Class inheritance section, define how the class that you create inherits rules from
superclasses:
a. Optional: To use pattern inheritance before direct inheritance when the system finds rules at run
time, select the Find by name first (Pattern) check box.
Pattern inheritance searches in superclasses based on prefixes to class names that end in a
hyphen.
b. In the Parent Class (Directed) field, enter the class name of the immediate parent of your new
class:

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

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

Note: During rule resolution, the system considers only direct parent classes. For example, class
C inherits from class B, and B inherits from A, but C does not inherit from A.
11. Click Save.
12. Optional: If you create a concrete class, check the class connection with the database by clicking
Test connection.
Note: For the test connection to work, ensure that the JDBC JAR file for the database platform is
present and included in the classpath, and that the prconfig.xml file contains an entry for the database
driver. For example, <env name="database/drivers" value="org.postgresql.Driver" />
Result: A window that contains the test results opens. The results include whether the class is
abstract or concrete, and the database and database table if the class is concrete.

Naming conventions for classes

Unified naming standards for classes help you manage your resources in a logical and efficient way.
You can avoid duplicating your content, maximize efficiency, and speed up application development
by sharing resources between multiple classes or class layers.

Class keys

When you define concrete classes, you can add keys to identify the classes. You can add the keys
when you create a class, or you can update the keys later.
 Organizing rules into rulesets
Creating a ruleset and a ruleset version
Creating branch rulesets
Deleting a rule

Naming conventions for classes

Unified naming standards for classes help you manage your resources in a logical and efficient way. You
can avoid duplicating your content, maximize efficiency, and speed up application development by sharing
resources between multiple classes or class layers.

For example, you can create class names that support class inheritance, so that you can reuse resources
across different classes. When you name a class RequestReviews-LoanRequests , you indicate that a new class
LoanRequests inherits resources from the RequestReviews class.

When you name classes, consider the following guidelines:

Use a noun for a class name, for example Customer or Address to distinguish classes from actions and
processes. For better readability, capitalize the first letter of each word, for example, CustomerDetails.
Ensure that your class name is descriptive and clearly conveys the purpose of the class.
Avoid using acronyms and abbreviations that are difficult to decode. The exception are common
acronyms, such as HTML.
Avoid including underscores (_) in class names.
Pega Platform provides a set of base classes that includes the Work-, History-, and Data- classes.
Create new classes only under the organization base class, for example, UPlusTelco-.
The system displays labels for class names on some of the forms, worklists, reports, and other areas of
an application. The system also displays a short description for the class. Therefore, use class names
that are self-explanatory and reflect the purpose of the work. Avoid using class names that reflect a
status or action, instead of a unit of work.
Choose class names that support pattern inheritance, as well as directed inheritance. For more
information about class inheritance, see Understanding class hierarchy and inheritance.
To distinguish hierarchy position and inheritance, use class names that visually reflect pattern
inheritance. For subclasses, include the names of all parent classes, including your top-level class,
separated by dashes. For example, if the parent class YourCoLoan-Request includes child classes for
mortgage and car loan applications, name the child classes YourCoLoan-Request-Mortgage and YourCoLoan-
Request-Auto.
Name related objects with consistent prefixes, so that you can quickly locate similar classes in an
alphabetical list.
Use the same naming conventions for class groups as for classes.

Organizing rules into rulesets

Creating rulesets
Understanding class layers
Creating classes

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

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

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

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

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

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

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

Creating rulesets
Understanding class hierarchy and inheritance
Deleting a rule
Rule resolution

General tab on the Class form

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

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

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

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

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

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

For a concrete class that does not belong to a class group, the system first examines the Keys array of
the Class form. If this array is not empty, it forms a key by concatenating values of the properties
identified in that array.
If the Keys array of this class is empty, the system uses class inheritance to locate a superclass (an
ancestor) for which the Keys array on this tab of the Class form is not blank. When such as class is
found, it concatenates the values of the properties in that Keys array to form the key.
For a concrete class that does belong to a class group, the system forms a key based on properties in
the Keys array of the Class Group form. As a result, any information in the Keys array of the Class form
is ignored.
Completing the Settings fields
The appearance of the General tab changes depending on whether you enter a class group, keys, or
neither. You cannot enter both a class group and keys. If you enter a class group, Pega Platform uses keys
defined in the class group.

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

Field Description

Indicate whether this class is to be abstract or concrete. Both abstract and concrete classes
can have subclasses.

Select If this class is to have persistent instances, select Concrete. (You cannot select Concrete if the class
name ends with a hyphen.)

Otherwise select Abstract.

Identify the ruleset version number that applies to this class. The Archive tools depend on the
version you enter here. The Export Archive tool includes this class instance if you export this
ruleset version or a higher-numbered version.
Created
However, version information in class rules is not used for rule resolution. You cannot define
in
Version multiple class rules with the same class name but different versions.

Complete this field when first creating a new class (with New or Save as). Alter this field later
in rare circumstances only.

Select one:

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

If this concrete class is derived from the Work- base class or the History-Work- class, select:

is a class group or
This belongs to a class group .
Class
Note: Concrete classes created in releases prior to PRPC Version 6.2 might not conform to this
restriction.

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

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

For an external class created through the External Data Table wizard, the initial value is does not
belong to a class group. Do not change this value.
 Field Select to cause Pega Platform to encrypt the Storage Stream of each instance of this concrete
Description
class when saved to the PegaRULES database, and to decrypt the Storage Stream when an
instance is retrieved from the database.

This check box appears only for concrete classes. It affects only instances of exactly this class,
not instances of any subclasses of this class.
Encrypt
BLOB Note: Determine whether you application is to use this feature early during the development
project. You cannot select or clear this check box if the database already contains instances of
the class.

Additional configuration is required to set up this capability. See Storage Stream encryption of
selected classes.

About the Class Group field

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

Field Description

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

The name of the class group you choose must match an initial portion of the class name.
Class
Choose this option when defining one or several concrete classes that define types of work items
Group
to be stored and processed as part of a single application, or the corresponding class derived
from History-Work-.

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

Completing the Keys fields

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

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

To create new Single Value properties of type Text with this class as the Applies To key part, enter the
property names into the Keys array before you first save the Class form. When you save the form, the
system creates both the new class and properties.
To use one or more properties already defined to apply to a superclass of this class as key properties,
do not enter them before you first save the Class form. Save the Class form once, and then use
SmartPrompt to select the properties that form the key.
For concrete classes derived from the Log- base class, the property pxCreateDateTime is usually the
final (or only) key part. In some high-volume systems, two log events may occur in the same
millisecond. If this can occur in your Log- class, choose additional properties to ensure uniqueness.
For concrete classes derived from the Index- base class, enter the properties pxInsIndexedKey,
pxIndexCount, and pxIndexPurpose in that order. No other properties can appear in the key.
For external classes, use of properties with a Type value of Date, Time, DateTime, or Double as key parts is
permitted, but may introduce rounding or uniqueness issues. Review the data representation on the
external database to confirm that it maps one-to-one with the Pega Platform representation.

Field Description

If two or more properties are to form the key, the order of rows in this array is
significant. Consider which order is likely to produce a natural or frequently presented
sort order in reporting or searching.
 Field For example, consider a class namedDescription
Data-County, with a key formed from a county
Keys name (such as Suffolk, for Suffolk county) and state code (such as MA for
Massachusetts). Assuming that reporting requirements present county information
within state, a natural order for the two key parts is state followed by county.

Optional. Leave blank if the concrete class is a subclass of a superclass that

corresponds to a class group. Also, leave blank if a parent (or higher superclass) of
this class is concrete and the key structure of this class is to be the same as the key
structure of the parent.

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

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

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

Optional. For concrete classes derived from Rule- or Data- for which a Rule-File-Form
is present, this text appears as field labels in the New dialog box.
Caption
In other cases, you can enter text to document why you chose this property to be part
of the key; the information you enter appears only in this field.

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

Completing the Rule Instances of this class fields

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

Field Description

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

When selected, causes the system to allow rules of this rule type to have
Allow selection of circumstance-based qualifications. If this check box is selected, at run time Pega
rules based on Platform uses circumstance-based processing at run time to select a rule, and
property values? these fields appear on the Save As form. See circumstance.
(circumstance-
qualified) This field appears only when the Allow multiple versions field is selected.

When selected, causes the system to allow rules of this rule type to have time-
Allow rules that are based qualifications. If this check box is selected, Pega Platform uses time-based
valid only for a processing at run time to select a rule, and these fields appear on the Save As
certain period of form. See time-based rules.
time? (date range
availability) This field appears only when the Allow multiple versions field is selected.
 Field Description
When selected, causes the system to cause the system to search up the class
Use class-based-
inheritance structure (using both pattern and directed inheritance) to find rules
inheritance to
of this rule type. If this check box is not selected, at run time Pega Platform
arrive at the correct
expects to find the rule in the current class only, not by searching through super-
rule to execute?
classes.

Completing the Class Inheritance fields

Indicate how this class inherits rules from super classes.

Field Description

Select to cause the system to use pattern inheritance before it uses directed inheritance
when finding rules at run time. Pattern inheritance searches superclasses based on prefixes
of the class name that end in a hyphen.
Find by
name Clear this check box to bypass pattern inheritance. Directed inheritance always occurs for
first all rule types with an Applies To key part.
(Pattern)?
If you selected belongs to a class group , this check box is selected.

After you save a Class form, you cannot change this setting.

Identify the class that is to be the immediate parent of this class:

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

If you selected is a class group in the This class field, enter Work- or a class that is derived from
the Work- base class here. (Or, enter History-Work- or a class that is derived from History-
Parent Work-, if you create a class to hold the history of work items. Such History-Work- classes are
class ordinarily created automatically.)
(Directed)
If you enter the longest possible prefix of this class ending in a hyphen, you can select or
clear the Find by name first (Pattern)? check box, with no difference in rule resolution
behavior or results. For example, if this class is named Work-Object-Mortgage and the
parent class is to be Work-Object-, Pega Platform performs the same search regardless of
the check box setting.

Caution: Do not assume that the "inherits from" relationship is transitive. Because only one
Parent class to inherit from (Directed) value is used by a rule resolution, it is possible that
class C inherits from class B, and B inherits from A, but C does not inherit from A.Note: You
cannot create a class derived from the Code- or System- base classes. These base classes
are reserved.

Testing the class-to-database table mapping

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

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

Results appear in a new window, identifying the database and database table that
correspond to this concrete class, and whether the class is an internal or external class.
Test
Connection
 This button appears only for concrete classes.

Note: For the test connection to work, the JDBC JAR file for the database platform must be
present and included in the classpath and the prconfig.xml file must contain an entry for the
database driver. For example:

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

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

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

Take these steps to work around this circular situation:

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

Organizing rules into classes

Locking tab on the Class form

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

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

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

Field Description

Keys

Optional. Leave this array blank in all but rare circumstances. If this field is blank, the Keys
properties from the General tab of this form is used to define a lock string.

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

Key
Optional. Not used.
Caption

Locking

For concrete classes, select this box except in rare situations. Select to allow the system to
lock open instances of the class when the Obj-Open or Obj-Open-By-Handle method specifies
locking.

However, for concrete classes derived from the Rule- base class, leave cleared. To restrict
updates to individual rules to one developer at a time, use rule checkout (by updating the
RuleSet to allow checkout, and updating the Operator ID to enable checkout), not locks.

Allow If this class is part of a class group, the Lock field on the class group form supersedes this
Locking Allow Locking? value.

If selected, a user cannot save or delete an instance within the scope of this class group unless
that user holds a lock on the object. Typically, activities acquire locks when they open an
instance to the clipboard.
 Note: If Allow locking? is selected, then when you use the Obj-Open, Obj-Open-by-Handle or
Field Description
Obj-Refresh-and-Lock method in an activity to open an instance within the scope of this class
group (with intent to update and save the instance), select the Lock check box parameter for
the method.

Object locking

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

Organizing rules into classes

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

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

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

AND

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

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

Viewing locks — Standard reports

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

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

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

Viewing locks — In an activity or flow

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

As a debugging aid, the standard section System-Locks.LockInfo and the standard harness Work-.LockInfo
can present information from that page to an application user. The LockInfo page contains these
properties:

pxExpireDateTime
pxLockHandle
pxOwnerID
pxUpdateOperator
 pxCreateDateTime

The lock string

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

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

Expired ("soft") locks

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

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

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

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

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

Releasing locks of other sessions

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

LockManager.unlock(StringMap, boolean)

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

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

Testing for locks

To test whether a work item is locked, an activity can call the standard activity Work-.WorkLock, which tries
to lock the work item. If it fails to acquire a lock, the SuccessInfo parameter is negative, indicating that the
work item is already locked. The FailureInfo parameter provides additional detail.
To test whether a lock is held on a page already on your own clipboard, call the function rule
isPageLocked(tools, pagename) .

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

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

com.pega.pegarules.engine.database.LockManagerImpl

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

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

Advanced tab on the Class form

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

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

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

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

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

Primary rule assembly

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

Primary Aspect – Select an interface or aspect. This list is populated by public methods defined in
com.pega.pegarules.pub.runtime.PublicAPI.
Primary Implementation Class – Type the name of a Java class that contains the rules assembly logic
for this class.

Secondary rule assembly

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

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

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

Full text search

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

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

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

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

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

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

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

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

Deprecated classes in Pega- rulesets are excluded from:

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

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

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

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

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

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

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

Organizing rules into classes

External Mapping tab on the Class form

The External Mapping tab is used primarily for external classes. External classes are created by the
Connecotr and Metadata wizard or the Database Class Mappings gadget and are linked by a Database Table
data instance to a table in a database other than the PegaRULES database.

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

Field Description

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

Column
For generated class rules, the name of a column in the external table.
Name

Property For generated class rules, the name of the property that represents the table column in the
Name Column Name field.

Exposing an embedded Single Value property value into a

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

For example, the embedded property .pyPreferences.pyNavigationPrefs.pyShowTabs manages whether a

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

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

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

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

Note:

In contrast to a Declare Index approach, the embedded property must be a scalar reference, not an
aggregate.
You can use this approach to expose one fixed scalar value within an aggregate property, such as
pyWorkparty(“Originator”).pyLastName for the last name of the Originator work party in a work item.
In most situations, however, you want to expose all values, not a single value; the technique described
here does not suffice.
Like other schema changes, the database administrator must add the column in every system that
contains the report rules (such as development, test, and production systems).
You can update Class rules that belong to foundation rulesets (for example, the Data-Admin-Operator-
ID class).

Organizing rules into classes

 Viewing database class mappings

About the Rename a Class wizard

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

Note: The Rename a Class wizard is designed to assist with refactoring applications that are in
development. It is not intended to be used on a deployed production application.

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

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

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

Starting the wizard

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

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

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

No rules are altered by the wizard until you click Next after reviewing additional rules to be changed on the
next-to-last page. For instructions on the forms, see:

Select Class to Rename and RuleSets

Verify Classes
Are there Work objects?
Are RuleSet Versions locked?
Are any rules checked out?
Rules that will be changed
Select additional rules to be changed
Results

Resuming the wizard

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

Prerequisites
You can rename a class if it meets these conditions:

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

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

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

1. The class is renamed.

2. Direct and pattern inheritance references the new class name. As a result, there will be no effect on
rule resolution.
3. If the option has been selected, Work- instances associated with the class are renamed.
4. All properties, activities, flows, and other rules that referenced the original class now reference the
class by the new name.
5. If the class is a work pool or defines an external data table, the Data-Admin-DB-Table instance is
updated to reflect the new class name.
6. The wizard creates a new History- class for the new class, and it will identify that the class has been
renamed. The History- class for the old class name is deleted.

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

Understanding class hierarchy and inheritance

Purging and archiving old work items

About the Delete a Class wizard

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

You can only delete classes that meet the following restrictions:

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

Starting the wizard

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

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

Help 1: Using the Delete a Class wizard.

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

Resuming the wizard

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

Note:

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

Deleting a class might render an application inoperative. Always back up the Pega Platform system before
deleting a class.

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

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

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

Classes related to deleted classes by directed inheritance are not deleted. If the specified class is a
subclass of Work-, all instances are deleted prior to the deletion of the class.

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

Using the Delete a Class wizard —

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

Using the Delete a Class wizard —

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

Using the Delete a Class wizard

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

Using the Delete a Class wizard —

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

Using the Delete a Class wizard —

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

Using the Delete a Class wizard —

Step 1: Select Class to Delete

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

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

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

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

About the Delete a Class wizard

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

Delete
Using the Delete a Class wizard —

Step 2: Display Classes to Delete

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

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

Click Next >> to complete the deletion.

Click << Back to select another class to delete.
Click Cancel to exit from the wizard without deleting any classes.
About the Delete a Class wizard

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

Using the Delete a Class wizard

Step 3: Display results and search for references

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

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

Select Reference Search

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

Don't search for references

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

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

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

About the Delete a Class wizard

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

Using the Delete a Class wizard —

Step 4: Display References

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

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

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

Click Finish to exit the wizard.

About the Delete a Class wizard

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

Using the Delete a Class wizard —

Step 5: End

This form appears when all steps are complete.

Click Finish to exit the wizard.

About the Delete a Class wizard

Deleting a rule
Save disk space by deleting rules that are no longer relevant in your application. For example, during
application development, you create a field property to capture a phone number, but later you need to
capture multiple phone numbers. You create a list property, and then delete the field property. As a result,
you improve the extensibility and user understanding of your application by providing only the rules that
your application requires.

Note: After you ship a ruleset, withdraw or block a rule instead of deleting it. You cannot search for deleted
rules.

When you develop a process in App Studio, your application might create additional rules, such as views,
that the final process does not require to function correctly. To ensure that you deliver only the minimum
number of rules that your application requires, remove such unnecessary rules.

The following conditions can prevent you from deleting a rule:

You cannot delete a rule that belongs to a locked ruleset version. However, in most situations, you can
create a blocked or withdrawn rule in your application that masks a rule (makes invisible to rule
resolution), that you no longer need in your application.
You cannot delete standard rules because they are part of the Pega Platform product. However, you
can override many standard rules.
You can delete a rule or data instance only in the following circumstances:
If an Access of Role to Object rule that is associated with your access role allows you to delete
rules or data instances.
If no Access Deny rules that are associated with your access role prevent you from deleting rules
or data instances.
You cannot delete a rule in which the Circumstance or Start Time fields are blank if your system
contains other rules with identical keys that are circumstance-qualified or time-qualified. Delete the
qualified rules first, and then delete the unqualified rule.
You cannot delete an Operator ID if the operator has any checked-out rules. Before you delete an
Operator ID, the operator needs to sign in, and delete or check in all rules in the personal ruleset.
You cannot delete a concrete class that contains instances.
You cannot delete a class, either concrete or abstract, if the system contains rules with the same class
name as the Applies To class. You receive a notification with a list of the rules that you need to delete
before you delete the class rule.
You cannot delete a ruleset version rule that identifies a non-empty collection of rules. First, you need
to delete each of the rules in the version.
You cannot delete a ruleset for which a ruleset version exists. Delete each version first.

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

2. In the Records explorer, expand the category of the rule that you want to delete, and then click its rule
type. For example: If you want to delete an activity, expand the Technical category, and then click
Activity.
3. In the list of rule instances, click the rule that you want to delete.
4. Click Delete.
5. In the Delete dialog box, describe the reason for deleting the rule, and then click Delete.
6. Optional: To undo your changes while you still have the rule open, click Restore.

What to do next: Recover a specific version of a deleted rule. For more information, see Recovering a
deleted rule.

Recovering a deleted rule

Facilitate application development by recovering one of the most recent versions of a deleted rule. For
example, if you accidentally delete a property, or delete a process rule that seems irrelevant, but you
later realize that you need the process to complete the case life cycle.

Performing a private edit

Copying a rule or data instance

Recovering a deleted rule

Facilitate application development by recovering one of the most recent versions of a deleted rule. For
example, if you accidentally delete a property, or delete a process rule that seems irrelevant, but you later
realize that you need the process to complete the case life cycle.

Note: Recovering a deleted rule is a different operation than restoring a rule immediately after deleting it.
By recovering a rule, you can roll back the rule to a specific version.

1. In the header of Dev Studio, click Configure Application Development Recent Actions .
2. Click View Deleted Rules.
3. Filter the relevant columns to narrow the results. For example: Filter the Type column to find
removed activities, as shown in the following figure:

List of deleted activities

4. Find the rule that you want to recover, and then click the value in the Rule name column to open the
rule.
5. Click Restore.
6. Click Save.

Restoring the earlier state of a rule

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

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

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

Benefits of rule resolution

The benefits of rule resolution include the following advantages:

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

Classes in rule resolution

Pega Platform defines data in a class hierarchy that follows the object-oriented paradigm. The hierarchy
starts with an ultimate class called @baseclass. Classes are subdivided into more specialized types of
classes. For example, the Requests- class can include specialized Requests-Loan- and Requests-Mortgage-
classes. Classes can contain rules that descend from the Rule- base class. Rules can inherit properties from
other rules through class hierarchy. In search for a rule that is defined in a particular class, the system
checks rules that are defined in the class, as well as rules defined in the ancestors of the class. The system
can hold multiple copies of rules, which are different, and any one of these copies might be useful at run
time, depending upon the situation. Rule resolution is a process by which Pega Platform determines which
rule to apply from the set of candidate rules. Many different rules can apply, so rule resolution checks all
the candidate rules to determine the most accurate way to perform processing.

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

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

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

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

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

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

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

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

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

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

Rule resolution inputs and output

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

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

For more information, see Understanding class hierarchy and inheritance.

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

For more information, see Setting rule status and availability.

In some cases, the value of a circumstance property.

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

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

Rule resolution process

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

1. The system checks the rules cache.

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

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

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

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

The purpose combines all the key parts of a rule.

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

The Applies to class that defines the activity.

The activity name.

In another example, for a field value, the key parts include:

The Applies to class, as above.

The field name, such as pyActionPrompt.
The field value, such as ViewHistory .
3. The system discards all unavailable rules and removes them from the temporary list.
4. The system discards inapplicable rulesets and versions.

The system removes from the list rules that belong to rulesets and versions that are not available for
the current requestor, which can be a user who is currently logged in, a REST API call, or any factor
that triggers rule processing. For example, if the current user can access the SampleRuleset:05-01-01
ruleset version, the system removes rules that belong to SampleRuleset:04 or SampleRuleset:06.

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

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

Note: This step is not applicable to rules that do not have the Use class-based inheritance to
arrive at the correct rule to execute check box selected in their class definition.
6. The system ranks the remaining rules in the list by analyzing the following aspects, in the following
order:
1. Class
2. RulesetNote: Default rules that you save to a branch or privately check out are in their own
ruleset.
3. Circumstance
4. Circumstance date
5. Version
7. The system adds the rules that remain in the list to the cache as selectable for use.
8. The system finds the best rule instance and checks for duplicates.

The process searches down the list for the first rule that matches the following criteria:
 The rule exactly matches a circumstanced rule.
The rule has the correct circumstanced date.
The rule is in the correct date/time range.

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

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

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

Rule resolution process

For example:

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

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

Rule resolution process in a class hierarchy

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

Ruleset list layers

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

Ruleset list usage during rule resolution

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

Viewing your application ruleset list

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

Using pattern inheritance for rule resolution

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

Creating a rule specialized by circumstance

Organizing rules
Organizing rules into rulesets
Organizing rules into classes
 Understanding class hierarchy and inheritance
Creating a rule

Ruleset list layers

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

Note: Order is significant at the layer, sublist level, and within each sublist.
Ruleset
Layer Notes
types

This ruleset, at the top of the ruleset list, holds rules checked out by the
operator. Such rules are not visible to any requestor except those of operators
who have the Allow Rule Checkout? check box selected on the Security tab of the
Operator ID instance. The name of the ruleset matches the Operator ID.
1 Personal
This single ruleset has no version and is included implicitly when the system
assembles the ruleset list at log-on. You do not need to reference the personal
ruleset on the Access Group form or any other form.

If the application has been localized, rulesets with names ending in a locale
suffix (such as _it_IT for Italian as spoken in Italy, or _fr_CA for French Canadian)
display here.
2 Localized
Typically, these rulesets contain only field values. If the application has not been
localized, this layer is empty.

If the application has been extended to support mobile devices, rulesets with
names ending in the suffix _mobile display in this layer. These rulesets contain
portals, sections, flow actions, navigation rules, and controls that are selected by
3 Mobilized rule resolution when the HTTP User-Agent value indicates that an HTTP request is
from a mobile device.

If the application has not been mobilized, this layer is empty.

Ruleset versions (if any) listed in the Production Rulesets array on the Layout tab
4 Production
of the Access Group form.

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

Any shared or component ruleset versions listed in the Component and shared
Application rulesets array on the General tab of the Application rule form for the current
5 application, in the order they display on the tab.
(current)
The system assembles layers 5 and 6 from ruleset versions listed in the
Application rulesets area of the General tab of any Application rule that it
encounters during log-on when it processes the data instances that contribute to
the rulesets list at login.

Ruleset versions for built-on applications referenced in the current application

rule. If an application references a lower built-on application, there is a layer for
6 Application
each application in the same relationship as the application rules, and the
(multiple) (built-on)
contents of the Component and shared rulesets area of application rules
referenced through the Built on application(s) field are ignored.

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

Pega-
 8 RULES:NN-
Ruleset A version of the foundation rulesets.
Layer NN Notes
types

Internationalization and localization

Mobile solutions

Ruleset list usage during rule resolution

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

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

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

Many other factors influence this process, such as:

Unavailable, final, or blocked rules

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

Viewing your application ruleset list

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

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

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

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

Using pattern inheritance for rule resolution

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

When the Find by name first (Pattern) check box (which corresponds to the Rule-Obj-
Class.pyPatternInheritance property) is selected on the Class rule form, the system uses pattern
inheritance for a class. Pattern inheritance causes the system to next search for a rule in classes derived
from the current class name by truncating, from the right, alphanumeric segments that follow a hyphen.

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

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

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

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

The ultimate base class @baseclass is searched last.

Example
For example, assume your application requests a rule from WalCare-Financial-Credit, which derives from
PegaCare-Financial-Credit, and WalCare-Financial-Credit uses pattern inheritance.

The system searches for the rule as follows:

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

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

Changing the scope of rules

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

Moving rules

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

Setting rule status and availability

Set rule status and availability to elaborate on the usage information that you provide, and ensure that
users interact with the correct version of your rule at run time. By setting rule status and availability,
you also define application behavior during rule resolution, and how users can interact with rules at
design time. As a result, you ensure that your application works correctly even if users apply
extensions and make modifications.

Creating a rule specialized by circumstance

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

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

Defining the input parameters of a rule

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

Defining the pages and classes of a rule

Many types of rules can access or update information on various clipboard pages when they run. Most
of these rule types include a Pages & Classes tab that you can use to provide important information
about what your clipboard pages will look like during execution.

Rule skimming for higher ruleset versions

Skimming is an operation of copying rules from your rulesets into a ruleset of a higher version.
Skimming improves the performance of your application because the system filters out rules that are
unavailable for rule resolution. Because the new ruleset contains only the highest rule versions,
skimming simplifies rule resolution and minimizes the rule data that you ship to a different version of
your application.

Adding a custom field

Associating custom fields with rules provides a flexible way to supplement your application with
metadata, such as a change order number or log file attachment.

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

Before you begin:

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

The class must allow rules in the target ruleset.

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

Rules must be checked in to be moved.

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

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

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

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

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

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

Result: When the process is complete, the form displays the results of the tool. Rules that are not moved
are marked with a red X. Hold the mouse over the red X for information about why the rule did not move.
Setting rule status and availability
Set rule status and availability to elaborate on the usage information that you provide, and ensure that
users interact with the correct version of your rule at run time. By setting rule status and availability, you
also define application behavior during rule resolution, and how users can interact with rules at design time.
As a result, you ensure that your application works correctly even if users apply extensions and make
modifications.

For example, if you need a core functionality of your application to remain unchanged, you can set the
status of rules that build the functionality as final, because users cannot override final rules.

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

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

Troubleshooting final rules

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

Troubleshooting blocked rules

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

Extension points

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

Base rules
Rule resolution

Troubleshooting final rules

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

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

Note: You cannot use circumstances or time-qualified rules to override a final rule.Note: You can override
a final rule with a sibling rule in a language-specific ruleset.

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

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

Setting rule status and availability

Extension points
Creating a rule
Copying a rule or data instance

Troubleshooting blocked rules

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

Blocked and blocked-by-another

A rule instance is blocked-by-another if its Availability value is set to Available but a higher-numbered
version of this rule (same name or key, same ruleset) has the Availability set to Blocked.

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

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

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

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

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

Blocked rules included in ZIP archives

When you create a ZIP archive containing a ruleset version, any blocked rules associated with that ruleset
Version are included in the archive (and remain blocked when uploaded into on a destination system).
On a destination system, a blocked rule can in some cases block a different set of other rules than it
blocked on the source system.

Blocked rules and skimming

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

Setting rule status and availability

Creating a rule
Copying a rule or data instance

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

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

Extension points in frameworks

An extension point is a rule (typically a blank or empty rule) that is marked as an Extension in the Status
field on the New or Save As dialog box. The corresponding property Rule-.pyMethodStatus does not
appear on the rule form, does not affect rule resolution or execution of the rule, and cannot be changed.

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

Setting rule status and availability

Creating a rule specialized by circumstance

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

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

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

Before you begin: If you want to circumstance a rule by using a set of conditions, create a circumstance
template and definition. For more information, see Creating a circumstance template and Creating a
circumstance definition.

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

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

a. In the CIRCUMSTANCE BY section, select Template.

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

a. In the CIRCUMSTANCE BY section, select Property and Date .

Circumstance b. In the Property field, enter a property to evaluate at run time. For example:
the rule by Enter LoanAmount.
property c. In the Value field, enter a value to evaluate against the property. For
example: Enter 5000.

a. In the CIRCUMSTANCE BY section, select Property and Date .

b. In the Date property field, enter a property that stores a date to evaluate at
run time.
c. Optional: To specify an exact starting time when an application can resolve the
rule, in the Start Date field, select the date.
d. Optional: To specify an exact time after which an application omits the rule in
rule resolution, in the End Date field, select the date.

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

Tip: In specific business scenarios, you can also circumstance rules by a combination of property and
date.
7. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
8. Update the values in the Context and Add to ruleset lists as appropriate.
9. Click Create and open .

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

Creating a circumstance template

Create a circumstance template to define a set of conditions that your application evaluates at run
time to determine whether a rule is available for rule resolution. By creating circumstance templates,
you deliver a flexible application that starts relevant processing under specified conditions, without
implementing complex and advanced business-logic solutions.

Creating a circumstance definition

Begin relevant processing in your application only under specified conditions by creating a
circumstance definition. When you implement circumstancing in your application, you provide flexible
solutions without defining complex logic. As a result, you increase efficiency and design an application
that is easier to maintain in the future if your business requirements change.
 Controlling the order of circumstance definitions

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

Creating a redirected rule

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

Base rules

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

Finding rules by circumstance

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

Specializing a case type

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

Rule resolution exceptions

Understanding rule resolution ranking exceptions can help you troubleshoot unexpected rule
resolution results.

Setting rule status and availability

Creating a rule
Rule resolution exceptions
Circumstance rule examples
Circumstance templates

Creating a circumstance template

Create a circumstance template to define a set of conditions that your application evaluates at run time to
determine whether a rule is available for rule resolution. By creating circumstance templates, you deliver a
flexible application that starts relevant processing under specified conditions, without implementing
complex and advanced business-logic solutions.

For example, in an application to review loan requests, you can define a circumstance template with
properties that hold a loan amount, a customer income, and an account type that the customer has. At run
time, the application starts relevant processing when the values of the properties meet specified conditions.
Creating a circumstance template is a first step in circumstancing a rule. As the template holds only
properties, you also need conditions to evaluate against the values of the properties.

1. In the header of Dev Studio, click Create Technical Circumstance Template .

2. On the Circumstance Template Record Configuration form, enter values in the fields to define the
context of the template:
a. In the Label field, enter text that describes the purpose of the circumstance template.
b. Optional: To change the default identifier for the circumstance template, click Edit, and then
provide a unique value in the Identifier field.
c. In the Context section, select the application to store the template.
d. In the Apply to field, press the Down arrow key and select the class that defines the scope of the
circumstance template.
e. In the Add to ruleset field, select the name and version of a ruleset that stores the circumstance
template.
f. Optional: To override the default work item that your application associates with this
development change, in the Work item to associate field, press the Down arrow key, and then
 select a work item.
For more information about your default work item, see Setting your current work item.
3. Click Create and open .
4. On the Template tab, in the Property field, press the Down arrow key, and then select the name of a
property that you want to evaluate at run time. For example: Select LoanAmount.
5. In the Label field, enter the name that corresponds with the property in a circumstance definition.
When you create a circumstance definition, which has a table layout, each row header displays a
property label.
6. Optional: To add more properties, click Add a row, and then repeat steps 4 through 5.
7. Click Save.

What to do next: Create a circumstance definition that stores conditions to evaluate against the
circumstance template. For more information, see Creating a circumstance definition.

Circumstance templates

Use a circumstance template rule to identify properties for multivariate circumstanced rules. A
circumstance template rule contains an array of properties such as .State, .Channel, and
.ClaimAmount that reference property values in one or more circumstance definition rules. These rules
define the value combinations for each of the properties defined in the circumstance template rule.

Changing the scope of rules

Setting rule status and availability
Creating a rule
Building logic and calculating values in your application

Circumstance templates
Use a circumstance template rule to identify properties for multivariate circumstanced rules. A
circumstance template rule contains an array of properties such as .State, .Channel, and .ClaimAmount that
reference property values in one or more circumstance definition rules. These rules define the value
combinations for each of the properties defined in the circumstance template rule.

Where referenced
Circumstance template rules are referenced by multivariate circumstance-qualified rules.

Multivariate circumstancing enables you to specialize a rule by more than one feature. For example, an
insurance company may be required to collect, for every state, claims that exceed a specific amount and
the method by which the claims were conveyed (letter, phone, email, and so on).

Create a circumstance template rule before you create a circumstance definition rule. For instructions, see
these Pega Community articles:

How to create a circumstance template rule

How to create a circumstance definition rule
How to create a rule with multiple circumstance properties.
How multivariate circumstancing works

Creating a circumstance template

Creating a circumstance definition

Begin relevant processing in your application only under specified conditions by creating a circumstance
definition. When you implement circumstancing in your application, you provide flexible solutions without
defining complex logic. As a result, you increase efficiency and design an application that is easier to
maintain in the future if your business requirements change.

For example, in a banking application, if your circumstance template includes a LoanAmount property, and the
definition includes the value 5000 with an operator >, the application resolves the circumstance rule only
when the loan request amount is greater than 5000.
Before you begin: Create a circumstance template that stores properties to evaluate by the
circumstance definition. For more information, see Creating a circumstance template.
 1. In the header of Dev Studio, click Create Technical Circumstance Definition .
2. On the Create Circumstance Definition form, enter values in the fields to define the context of the
definition:
a. In the Label field, enter text that describes the purpose of the circumstance definition.
b. Optional: To change the default identifier for the circumstance definition, click Edit, and then in
the Identifier field, provide a unique value.
c. In the Template Name field, press the Down arrow key, and then select the circumstance
template that your circumstance definition implements.
d. In the Context section, select the application to store the template.
e. In the Apply to field, press the Down arrow key and select the class that defines the scope of the
circumstance definition.
f. In the Add to ruleset field, select the name and version of a ruleset that stores the circumstance
definition.
g. Optional: To override the default work item that your application associates with this
development change, in the Work item to associate field, press the Down arrow key, and then
select a work item.
For more information about your default work item, see Setting your current work item.
3. Click Create and open .
4. On the Definition tab, click the column header to choose which operations the column supports:
For columns that evaluate properties from the template against a single value, select an operator
from the Use Operator list, for example >.
For columns that evaluate properties from the template against a range of values, select the Use
Range check box, and then choose operators from the Starting Range and End Range lists, for
example >= and <=.
5. Click Save.
6. Click a cell in a table that you want to define, and then enter a value or an expression that evaluates
properties in the template. For example: To evaluate loan amounts greater than 5000, use a single
operator >, and then enter 5000.
7. Optional: To provide more values for evaluation, add rows to the table:
To add a row before the current cell, on the toolbar, click Insert Row Before, and then repeat
step 6.
To add a row after the current cell, on the toolbar, click Insert Row After, and then repeat step
6.
Tip: As your application evaluates the table from top to bottom, to save time and resources, place the
most likely outcomes at the top of the table.
8. Optional: To ensure that your application can process the table, check the table for conflicts by
clicking Show conflicts on the toolbar. Result: A warning icon appears in rows that are unreachable
or empty.
9. Click Save.

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

Date circumstance rule

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

Circumstance rule examples

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

Circumstance definitions

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

Date combinations and business requirements

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

Changing the scope of rules

 Setting rule status and availability
Creating a rule
Building logic and calculating values in your application

Date circumstance rule

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

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

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

Using more than one time-qualified rule

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

Contrasting time-qualified rules and historical processing

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

Setting rule status and availability

Creating a rule specialized by circumstance
Circumstance rule examples

Using more than one time-qualified rule

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

1. Examine the end dates on each candidate time-qualified rule. Choose the rule or rules that have the
nearest end date, discarding others.
2. If only one candidate remains, that rule is the result of this phase of rule resolution processing.
3. If two or more candidates remain, the one with the most recent start date is selected.

Date circumstance rule

Contrasting time-qualified rules and historical processing

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

Date circumstance rules

Historical processing capability

How circumstance rules evaluate time

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

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

Result Date property Start Date End Date

Rule to be effective only if the value of the specified

Select Select Select
date property occurs within a date range

Rule to be effective only if the value of the specified

Select Select
date property occurs after a certain date

Rule to be effective only within a date range Select Select

Rule to be effective only after a certain date Select

How historical processing evaluates time

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

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

Creating a rule specialized by circumstance

Circumstance rule examples

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

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

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

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

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

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

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

A single rule can contain both a circumstance property and a date circumstance property. For the
circumstance property value, an exact match is required. For the date circumstance, when a date property
is specified its value must occur after the specified start date and before the end date. If a date property is
not specified, the system time at the time of processing should occur after the specified start date and
before the end date.
Note: If two base rules with the same Apply to key part and family name both have one or more
associated property circumstanced rules, the same circumstance property must be used. For example, if
activity MyClass.Alpha has an associated circumstanced rule using property .State, then another activity
MyClass.Alpha cannot have a circumstance rule with any property other than .State.

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

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

Multiple properties in a circumstance>

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

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

Circumstance Templates (Rule-Circumstance-Template rule type)

Circumstance Definitions (Rule-Circumstance-Definition rule type)

Note:

For decision tables, you can redirect one circumstanced rule to another circumstanced rule (a peer
with the same base rule), to reduce the number of distinct rules that you need to maintain. Select the
Redirect this rule check box on the Results tab.
A rule cannot be a circumstance if another rule of the same type and name exists in a different class,
even if the classes are unrelated and have no inheritance relationship, even if the conflicting rules are
set to withdrawn rule. This is because the Apples To class of a rule is not taken into account when
looking for conflicting circumstance rule instances, only the name.

Creating a rule specialized by circumstance

Finding rules by circumstance
Rule resolution
Circumstance templates
Circumstance definitions

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

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

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

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

Creating a circumstance definition

Date combinations and business requirements

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

Specify date Specify start Specify end

Business requirement
property date date

Rule to be effective only if the value of the specified

Yes Yes Yes
date property occurs within a date range

Rule to be effective only if the value of the specified

Yes Yes No
date property occurs after a certain date

Rule to be effective only within a date range No Yes Yes

Rule to be effective only after a certain date No Yes No

Creating a rule specialized by circumstance

Controlling the order of circumstance definitions

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

Consider a situation in which a circumstance template includes a property that holds a loan amount. Two
circumstance definitions correspond with the template; one definition that evaluates the property against
values greater than 4,000, and a second definition that evaluates a property against values greater than
7,000. A customer creates a loan request for 10,000. Because both circumstance definitions evaluate to
true, you can select which definition you want your application to use.
Before you begin: Define a circumstance template that stores properties and at least two circumstance
definitions that store values to evaluate against the template. For more information, see Creating a
circumstance template and Creating a circumstance definition.

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

2. Expand the Technical category and click Circumstance Template.
3. In the list of circumstance templates instances, click the template that you want to open.
4. Click the Definitions tab. Result: The All Definitions section displays all circumstance definitions
that correspond to the open circumstance template.
5. In the Priority Definitions section, in the field in row 1, enter the circumstance definition that you
want your application to run first.
6. To add more circumstance definitions, click Add a row, and then in the row that appears, enter the
definition that you want your application to run next.
Tip: You can also drag a field to a different position in the list to change its run-time priority.
7. To check the correctness of your circumstance definitions, on the toolbar, click Show Conflicts.
Result: A read-only decision table opens in a separate window that displays all the definition values
for all the circumstance definition rules in the specified order. A warning icon appears next to the rows
of the table that are unreachable. A warning message also appears when you attempt to save a form
that contains conflicts. Even though the tables might not have any conflicts individually, conflicts
might generate when the system assembles the definitions as a single table at run time.
8. Click Save.

Creating a rule
Building logic and calculating values in your application

Creating a redirected rule

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

1. Create a base rule for the decision table.

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

Redirected rule

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

Decision tables
Creating a rule specialized by circumstance

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

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

Benefits
Redirection can simplify maintenance of a set of circumstance rules. For example, an application might
include a decision table named SalesTax that computes state sales taxes for a state and is circumstanced
by state code, such as VA for Virginia.

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

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

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

Note:

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

Creating a redirected rule

Circumstance rule examples
Creating a rule specialized by circumstance

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

A base rule must exist for every circumstance rule.

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

Creating a rule specialized by circumstance

Setting rule status and availability
Circumstance rule examples

Finding rules by circumstance

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

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

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

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

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

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

Creating a rule specialized by circumstance

Setting rule status and availability
Circumstance rule examples

Specializing a case type

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

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

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

Note: Case types support specialization by a single-value property. The property that you specify is
used for this version and all future, specialized versions that you create. This means that the
autocomplete field is hidden the next time that you follow this procedure.
 4. Click + Add specialization.
5. Define a property value for the circumstance by using one of the following fields:

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

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

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

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

6. Click Save.

Result:

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

Rule resolution exceptions

Understanding rule resolution ranking exceptions can help you troubleshoot unexpected rule resolution
results.

Privately edited and branched rules

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

1. MyRule in myusername@ ***

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

Circumstance rules outside of the matched ruleset

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

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

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

Rule resolution

Creating a rule specialized by a class or ruleset

Provide a version of a rule that your application triggers only during resolution of rules that belong to a
specified class or ruleset. When you define the conditions for a rule resolution, you ensure that users
interact with actions and the application behavior that are relevant in a given scenario. You also save time
and resources because you promote reuse across your application.
Consider a scenario in which Vehicle-Insurance and Loan-Request classes in your application are outside a
class hierarchy and have no shared rulesets, but you want to apply a service-level agreement (SLA) rule
from the Loan-Request class to the Vehicle-Insurance class. You can specialize the SLA rule so that your
application can resolve it during processing of the Vehicle-Insurance class.

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

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

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

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

Rule resolution
Building logic and calculating values in your application
Copying a rule or data instance

Defining the input parameters of a rule

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

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

Note: Some rules do not support parameters or support only a subset of the options below. Names of fields
may vary, based on the type of rule that you are updating.

1. Open the form for a rule that supports parameters by searching for the rule or using the Application
Explorer.

2. Click the Parameters tab.

3. In the Parameters section, repeat the following steps for each input parameter that your rule
supports:

1. Click the Add item icon.

2. In the Name field, enter a unique identifier.

3. In the Description field, enter text that describes how your rule logic processes the input
parameter.

4. In the Data Type list, select a format for the input parameter.

5. To require a non-null value for the input parameter, select Yes from the Required? list.

Do not make Boolean input parameters required because your application can interpret a false
 value as a null or blank value.

6. To set the initial value of the input parameter, enter a value in the Default Value field that
corresponds to the format that you select in the Data Type list.

4. For each input parameter with Data Type set to Page Name, add an entry to the Pages & Classes
tab of the form.

5. Update your rule logic on other tabs of the rule form to reference the input parameters by using the
notation param.[ input parameter name ] .

6. Click Save.

You can test your changes by running the rule and providing values for the input parameters when
prompted.

Prompting users for parameter values

You can prompt users for values when they run a rule that has input parameters. By displaying a list of
options instead of a blank text box, you can help users provide information quickly and accurately.

Defining the pages and classes of a rule

Prompting users for parameter values

You can prompt users for values when they run a rule that has input parameters. By displaying a list of
options instead of a blank text box, you can help users provide information quickly and accurately.

Note: Some rules do not support parameters or support only a subset of the options below. Names of fields
may vary, based on the type of rule that you are updating.

1. Define the input parameters for your rule.

2. In the header of the rule form, click Actions > View references to display a list of rules that call your
rule.

3. Inspect the list to ensure that your rule runs in response to an action that a user performs, such as a
flow action, because parameter prompting does not occur when a rule runs programmatically.

4. Click the Parameters tab.

5. In the SmartPrompt type field, enter the first key part, which is typically the class, of the input
parameter.

For example, you can enter Rule-Message to display a list of messages that are available in the run-time
class path.

6. To refine the options in the list, enter the second key part of the input parameter in the Validate as
field.

For example, you can enter pyCaption when the SmartPrompt type field is set to Rule-Obj-FieldValue to
display only field values with a field name that contains "pyCaption".

You can also reference a property in this field.

7. Click Save.

You can test your changes by running your rule.

Defining the input parameters of a rule

Configuring and working with optional actions in case types

Defining the pages and classes of a rule

Many types of rules can access or update information on various clipboard pages when they run. Most of
these rule types include a Pages & Classes tab that you can use to provide important information about
what your clipboard pages will look like during execution.

Setting up rule prompting during when you configure forms. For example, if you specified that a page
belongs to the Work-class in the Pages & Classes tab of an activity, when the page is used as a step
page, prompting shows results from the Work- class.
Configuring rule validation. The information specified in the Pages and Classes tab defines how rule
references are validated during rule validation.
Applying the default class for list elements. When you define a list or group page on the Pages and
Classes tab, the system automatically sets the class of those elements when new entries are added.

Guidelines
To complete a Pages & Classes tab, follow these guidelines:

Leave this tab blank if the other tabs of the rule do not reference any pages.
Complete this tab to describe the clipboard context expected at run time.
Page names are case-sensitive, so be sure to match the case of the page name.
Enter the name of each page referenced explicitly on the other tabs of the rule form. For rules that
contain HTML or XML text , such as correspondence or HTML rules , the reference can be inside a JSP
tag or directive.
To set the class of the primary page, add a row that has no value for the page name and the desired
class name.
If you use the keyword Top on other tabs of the rule form, such as in embedded properties, add a row
with the keyword Top in the Page Name column and the class of the top level page in the Class
column. You frequently do this when the name of the top-level page name varies in different settings.
For an embedded page enter the full page name. You can also enter the full page name starting with
the top-level page name or with the keyword Top. For List and Group arrays, use trailing (). For
example:
myPage.ListA().PageA
myPage.ListA().listB()

Page names must be absolute property references. Relative references, such as .myEmbeddedPage are not
supported. Instead, use the keywords Primary or StepPage to make the path absolute. For example:

Primary.myEmbeddedPage
StepPage.myEmbeddedPage
You do not need to list all the clipboard pages expected to be on the clipboard, only those that are
referenced in this rule.
For HTML rules, XML Stream rules, and other stream rules containing JSP tags, list all the pages
identified in the HTML text, including system pages ( pxRequestor, pxProcess, pxThread, and their embedded
pages, if mentioned).
You cannot use the keywords $ANY or $CLASS in the Class column.
Do not use the keywords $ANY, $CLASS, or $None in the Class column; these keywords are
deprecated.
If the Class column is blank, the Applies To class of the rule is used by default.
For rules that run in the context of a primary page, you can leave the page name blank for greater
flexibility. (The class of the primary page matches the Applies To key part of the rule.)
You must have classes for data pages defined on the Pages & Classes tab. When you add a
parameterized data pages to the tab, do not use parameters or brackets.

Note:

The context at run time often differs from the context at design-time.
You can enter rows in the list in any order.
You cannot use the Top keyword in the Pages & Classes tab of a list view or summary view rule.
Using the Top keyword in a data transform does not reference the top-level page.
You must list embedded pages in the Pages & Classes tab if the class of the embedded page varies
from the class defined for the property at run time.

Run-time processing
The pages that are present when a rule is running might vary from execution to execution. The system
neither requires nor checks that all the pages listed are present each time it runs the rule. It only
determines it can find the properties needed to perform the current execution.
In some situations, the class of a page may vary from execution to execution. If all the properties
referenced are available in a common parent class, you can list the parent on this tab, even though the
page belongs to a subclass.

For example, an activity may operate on a page named Customer that, in some situations, has the class
Data-Account-Savings and in other cases has the class Data-Account-Checking. If all the properties that the
activity needs — for example CurrentBalance and AccountOpenDate — are defined in the Data-Account-
class, you can list Data-Account- in the Class column.

However, if the activity needs to access both checking and savings data at once, the activity needs to work
with two pages — one of each class — with distinct page names.

Identifying pages in your application

Managing the number and names of clipboard pages referenced in your application is important. Using too
many pages or omitting to remove the pages when no longer needed can add to the run time memory
demand of your applications. Misspelling page names or having two copies of one page (with different
names) can also hurt performance or make testing difficult.

Use the Data Designer Usage tab to see the pages that use a data type.

Special cases
Certain rule forms offer more capabilities for greater power and flexibility:

This functionality is not supported. Use a data page instead. For three rule types — Declare
Expression, constraints, and when condition rules — you can define page names that start with the
keyword locate and that use an activity to search or assemble the page needed. These pages are known
as locatable pages.
For six rule types — including activities and correspondence — pages with names that start with the
keyword prompt are known as indirect pages. This facility allows a calling activity to share multiple pages
with a called activity, for example. When the called activity references a property on a page named
promptALPHA, the system searches the clipboard for a page named ALPHA. Note: This feature has
been deprecated.

Page names and reserved pages

A page is a data structure that holds name-value pairs.

Using the Clipboard tool

Page names and reserved pages

A page is a data structure that holds name-value pairs.

Most pages are named; the names of pages may arise from any of four sources:

Literal values entered into a rule such as a parameter to the Page-New method.
System-created pages with reserved names and purposes, such as the requestor page.
Names used by convention in a collection of rules designed to operate together
Property names (for embedded pages)

Valid page names

A page name can contain only letters, digits, and the underscore character. Start the page name with a
letter.

Several keywords identify elements in specific operations. Using keywords as a page name is not
recommended: param, local, locate (unsupported), primary, steppage, mysteppage, top, parent, or current.

Do not use any of the following names or patterns as a page name, where an asterisk indicates one or more
characters: pxNode, pxRequestor, pxThread, LISTVIEW_*, locate* prompt*, $*, px*, pz*, or py*.
Special page name prefixes
You cannot use certain prefixes and keywords as page names, as they have a special meaning:

local – Not a page, a keyword indicating that the name that follows the word "local" and the period is a
local variable, not a property.
locate – A prefix to a page name (in lowercase), indicates that this page is retrieved or located at
runtime through an activity of type Locate. This prefix is unsupported. Locatable pages have been
replaced by data pages.
mode – Identifies an indirect page reference.
param – Identifies the parameter page for an activity. This page structure is not part of the clipboard.
parent – In the context of an embedded page, identifies the immediately containing page to which the
embedded page belongs. This keyword might appear more than once in a property reference. You
keyword is used in Declare Index rules, decision tables, decision trees, and map values. You can also
use the PARENT keyword in the Step page field in activities. You cannot use this keyword in data
transforms.
prompt – As a prefix portion of a page name, not a keyword, identifies an indirect page reference in a
Call or Branch.
primary – In the context of an activity, refers to the primary page of that activity.
top – In the context of an embedded page, identifies the top-level page to which the current embedded
page belongs.

The prefixes D_ and Declare_ in a page name indicates a data page, a page that is created and updated only
by data page rules. The properties on this page are "read-only" to normal requestor processing. To avoid
confusion with such pages , don't create pages named Declare_zzzzz or D_zzzzz in other processing.

Except as noted, case is not significant in keywords: Param.Country, PARAM.Country and param.Country all
reference the same value.

Page names used by convention

Many standard activities and other standard rules use these page names by convention. To utilize these
standard rules, follow these naming conventions in the rules you create.

Page Name Description

When a single assignment object is open on the clipboard, the page is named NewAssignPage.
NewAssignPage If your application involves multiple work items (or multiple assignments) on the clipboard,
you can use other names.

By convention in standard flow processing activities, when a single cover work item is
pyCoverPage
opened onto the clipboard, the page is named pyCoverPage.

pyOutput Created by Process API activities.

By convention in standard flow processing activities, when a single (non-cover) work item is
pyWorkPage
opened onto the clipboard, the page is named pyWorkPage.

Created during unit testing of a rule with the Run toolbar button. The class of this page
RuleToRun
matches the rule type. See Unit testing a rule with the Run toolbar button.

System-created pages
These top-level pages are present in the clipboard of every authenticated requestor:

Page Name Description

Process
A named page of class Code-Pega-Process containing system-wide information, such as
page (
information from the Data-Admin-System instance.
pxProcess )

Requestor
A named page of class Code-Pega-Requestor. Created at log in and contains information
page (
about your access roles, RuleSet list, and TCP and HTTP protocol parameters.
pxRequestor )
 Page Name
Thread Description
page ( A named page of class Code-Pega-Thread, identifies a named context of clipboard pages.
pxThread ) The first Thread for a requestor is named STANDARD.

Contains information from the requestor's current access group (Data-Admin-Operator-

AccessGroup
AccessGroup class). This page does not exist for guest (unauthenticated) users.
Contains information from the requestor's organization ( Data-Admin-Organization class).
Org This page does not exist for guest (unauthenticated) users. This page does not exist for
guest (unauthenticated) users.

Contains information from the requestor's organization ( Data-Admin-Organization class).

OrgDivision
This page does not exist for guest (unauthenticated) users.

Contains information from the requestor's Operator ID ( Data-Admin-Operator-ID class). This

OperatorID
page does not exist for guest (unauthenticated) users.

Other

Page Name Description

Produced by execution of a list rule ( Rule-Obj-List rule

pyQueryResultPage
type).

Indirect pages
Viewing test coverage reports
Clipboard tool
Using the Clipboard tool

Rule skimming for higher ruleset versions

Skimming is an operation of copying rules from your rulesets into a ruleset of a higher version. Skimming
improves the performance of your application because the system filters out rules that are unavailable for
rule resolution. Because the new ruleset contains only the highest rule versions, skimming simplifies rule
resolution and minimizes the rule data that you ship to a different version of your application.

Skimming collects the highest version of every rule in the ruleset and copies the rules to a new major or
minor version of that ruleset on the same system. Rule availability and the type of skimming determine
which rules the system carries to a higher ruleset version.

You can select between a major skim and a minor skim. The skim type corresponds with the digits in a
ruleset version number. The two first digits define the major version, and the two middle digits define the
minor version. For example, in the ruleset version 06-09-10, 06 indicates the major version, and 09 corresponds
with the minor version. The major ruleset version typically specifies a release of your application or other
significant changes, while the minor version relates to an enhancement or a less extensive change in your
application. When you select a skim type, consider changes that you want to merge in the higher ruleset
version. The final two digits correspond with patch releases and do not have a separate skim type
associated with them. Skimming copies rules so that all your rules in lower ruleset versions remain
unchanged. During skimming, the system omits rules in the major versions that are lower than the major
version that you specify. For example, if you opt to skim 02-05-02 into 03-01-01, the system ignores any rules in
the version 01-XX-XX.

The following table displays which rules you can include in a higher ruleset version by using either the
major or minor skimming type:

Skim type/Rule availability Available Not Available Final Withdrawn Blocked

Major Yes No Yes No Yes

Minor Yes No Yes Yes Yes

The update history of the new skimmed rule contains only one instance that reflects the date and time of
the rule creation based on the skim operation. The history of the source rule is available and remains
unchanged.

Creating higher ruleset versions by skimming rules

Improve the performance of your application and simplify the rule resolution by skimming rules to
create higher version rulesets. Skimming filters out rules that are not available for rule resolution and
makes rule management more convenient.

Organizing rules into rulesets

Creating rulesets
Defining the security of a ruleset
Deleting a ruleset

Creating higher ruleset versions by skimming rules

Improve the performance of your application and simplify the rule resolution by skimming rules to create
higher version rulesets. Skimming filters out rules that are not available for rule resolution and makes rule
management more convenient.

You can select between two types of skimming, a minor skim and a major skim. The minor skim moves
rules to a higher minor version of your application, for example, after you implement new enhancements.
You can check the minor ruleset version by analyzing the middle two digits of the ruleset version. An
example of a minor skim is skimming rules in 06-05-01 through 06-09-25 into the 06-10-01 ruleset versions. The
major skim moves rules into a higher major version of your application, such as a new release. The two first
digits in the ruleset version correspond with the major version. A major skim is skimming rules 06-05-01
through 06-09-25 into the 07-01-01 ruleset versions.
Before you begin:

Check in all the rules that you want to skim. For more information, see Checking in a rule.
To ensure that users cannot edit lower versions of the ruleset after skimming, secure the lower ruleset
versions. For more information, see Defining the security of a ruleset.

During skimming, the system copies rules to a new ruleset with a higher version number. The rules in the
lower versions remain unchanged in your system.

1. In the header of Dev Studio, click Configure System Refactor RuleSets .

2. On the RuleSets tab, in the Refactor Rulesets Utilities section, click Skim a Ruleset.
3. In the Skim to create a higher version window, define the skimming settings:
Choices Actions

a. Select the Major Version RuleSet Skim radio button.

b. In the RuleSet list, select a ruleset that you want to skim.
c. In the From Major Version list, select an existing major version that you want to
skim to a higher version.
Perform
d. In the To New Version field, enter a ruleset version that you want to create with
a major
skimming.
skim
Ensure that the new version relates to the skimming type.
For example: If you want to perform a major skim on the 06-09-25 version, enter 07-01-
01.
e. Click Skim.

a. Select the Minor Version RuleSet Skim radio button.

b. In the RuleSet list, select a ruleset that you want to skim.
c. In the Starting Version and Ending Version lists, select a version range of the
ruleset that you want to skim. For example: Select 06-05-01 as a start version and
Perform 06-09-25 as an end version.
a minor d. In the To New Version field, enter a ruleset version that you want to create with
skim skimming.
Ensure that the new version relates to the skimming type.
For example: If you want to perform a minor skim on the 06-05-01 to 06-09-25 version
range, enter 06-10-0.
e. Click Skim.
Result: The window displays the progress and the results of the skim after the process is complete.
 4. If any errors occur, click the Total Errors link.
You can only access the list of errors from the Skim to create a higher version window.

What to do next:

Research and resolve errors that occurred during the skim operation.
Update access groups or application rules to make the new major version available to appropriate
users. For more information, see Learning about access groups.
To ensure that users can edit only the highest ruleset version, secure lower ruleset versions. For more
information, see Defining the security of a ruleset.
To decrease the number of rules in your system and speed up rule resolution, delete rules in the lower
major versions. For more information, see Deleting a ruleset.Note: Ensure that your organization
accepts deleting rules that are no longer in use.

Organizing rules into rulesets

Creating rulesets

Adding a custom field

Associating custom fields with rules provides a flexible way to supplement your application with metadata,
such as a change order number or log file attachment.

To add a custom field, do the following.

1. Click the History tab of a rule form.

2. Click Add Field to open the Add custom fields dialog.
3. Choose a name from the list of properties to populate the Name field. Alternatively, enter a string
(letters and digits only) directly in this field to create a new property with the specified name.
4. If you entered a string in the Name field, select a Type for the property. For existing properties, this
field is populated and read-only.
5. From the RuleSet version drop-down box, select the appropriate ruleset version.
For properties of Type File:
1. Enter a brief description of the file in the Description field.
2. Select the New or Existing radio button to indicate how you will provide the file.
3. Click Browse to upload a file from your local system. The file you specify becomes an
instance of Rule-File-Binary.
4. Click the Pick a file button to select a file previously linked to this property.
For properties of Type Text:
Enter text to pair with the property in the Value field.
Alternatively, click the Open icon to select a value previously applied to this property.
6. Click Submit to close the dialog.
7. Click Save in the rule form header to persist your changes. The Custom Fields list is automatically
updated by the rule form.

Viewing rule history

Checking out a rule

To avoid accidental rule changes or conflicts that might result from multiple developers working on the
same rule, perform a check out, so that you can lock the rule and safely make changes to it. By checking a
rule out before editing, you avoid unwanted rule changes, and as a result save time and maintain a better
quality application.

You can only check out rules that belong to an unlocked ruleset. If you want to edit a rule that belongs to a
locked ruleset, perform a private edit. For more information, see Performing a private edit.Note: When you
make updates to your application in App Studio, Pega Platform automatically manages the check-in and
checkout process.

1. In the navigation pane of Dev Studio, click Records, expand the category that contains the rule that
you want to edit, and then click the rule.
2. In the header of the rule form, click Check out.
Your application places a copy of the original or base rule in your personal ruleset. No other user can
check out this rule until you check in your changes.
3. Modify the rule as appropriate.
 4. Click Save.
Your application saves your changes into the checked-out version of the rule. These changes are
visible only to you. When you run rules in your application, they resolve to only your checked-out
version.

What to do next: Make your changes available to other developers of your application by checking in the
rules that you edit. For more information, see Checking in a rule.Note: You do not have to check in your
changes immediately. You can log out and return to a checked-out rule later or click Discard to remove the
rule from your personal ruleset.

Standard rule checkout

The Check out button appears for standard checkouts when all the following criteria are met:

Private checkout

You can perform a private checkout of a rule that is typically not available for a standard checkout. For
example, you can check out a rule in a locked ruleset to modify it and test the changes.

Checking out a rule to a branch

You can check out a rule to a branch so that you can make changes to a rule and then save it in the
branch ruleset. For information about rule resolution for rules saved to a branch ruleset, see .

Viewing your checkouts and accessing bulk actions

Click the Checkouts icon in the Dev Studio header to open a list of rules checked out by your operator.
Rules are organized by type, name, and Applies To class. In the Private overlay, you can perform the
following actions:

Rule checkout notes

Note the following information when you are checking out rules:

Rule checkout tips

You can use several features to determine that you have checked out all the rules in your application
You can also use other features to undo changes and to override the default check-in procedure.

Personal ruleset

Users who have the Allow rule check out option enabled for their operator IDs can place copies of rule
instances into a personal ruleset. The name of this ruleset is the Operator ID, such as
john_sawyer@abc.com. The personal ruleset is sometimes called the private ruleset.

Checking in a rule

To make your changes available to your development team after you check out and edit a rule, check
in the rule. When you check in edited or updated rules, you contribute to the efficient development of
your application and avoid errors that might occur when other developers work on the same rule.

Rule check-in process

Configuring Project Management Framework (PMF)

Standard rule checkout

The Check out button appears for standard checkouts when all the following criteria are met:

The rule belongs to a ruleset that has the checkouts enabled.

For this operator, the Allow rule check out check box on the Security tab of the Operator ID form is
selected.
The rule is not locked by another user or in a locked ruleset. A locked rule displays a padlock next to
the Check out button. Click this icon to see the reason it is locked.

Other operators can use Check out to branch or Private edit until you release the lock.

Checking out a rule

Private checkout
You can perform a private checkout of a rule that is typically not available for a standard checkout. For
example, you can check out a rule in a locked ruleset to modify it and test the changes.

The Private edit button appears when all the following criteria are met:

You have the pxAllowPrivateCheckout privilege, which is typically granted through a role on your
access group. The standard access role PegaRULES:SysAdm4 provides this privilege.
The rule is not available for regular checkout, usually because it is already checked out to another
user or because its ruleset version is locked.
The rule belongs to a ruleset that has the checkouts enabled.
Your Operator ID is allowed to check out rules. For more information, see Security tab on the Operator
ID form.

Performing a private edit

To ensure that your application meets the unique needs of your customers, you can modify a rule that
is unavailable for regular checkout by performing a private edit. Check out rules as private edits to
edit rules that belong to locked rulesets.

Performing a private edit

To ensure that your application meets the unique needs of your customers, you can modify a rule that is
unavailable for regular checkout by performing a private edit. Check out rules as private edits to edit rules
that belong to locked rulesets.

Private edits are useful for quick debugging without interrupting other team members, because during a
private edit other system architects can edit a rule at the same time.
When you perform a private edit, you edit a rule in an isolated sandbox, in which you can make and then
test your changes. As a result, you maintain a good quality application and avoid creating errors, because
during a private edit the original ruleset that contains your rule remains unchanged.

1. In the navigation pane of Dev Studio, click Records, expand the category that contains the rule that
you want to edit, and then click the rule.
2. In the rule form, click Private edit.
3. In the dialog box that appears, click Continue with private edit.
The system saves a copy of the rule in your personal ruleset. Rules in your personal ruleset do not
affect other users’ run-time experiences, or the actions that they can perform on this rule.
4. Edit the rule.
5. Click Save.
Your application saves your changes into the checked-out version of the rule. These changes are
visible only to you. When you run rules in your application, they resolve to only your checked-out
version.

What to do next: Make your changes available to other developers of your application by checking in the
rules that you edit. For more information, see Checking in a rule.

Configuring Project Management Framework (PMF)

Checking out a rule to a branch

Checking out a rule to a branch

You can check out a rule to a branch so that you can make changes to a rule and then save it in the branch
ruleset. For information about rule resolution for rules saved to a branch ruleset, see Rule resolution
exceptions.

Because you cannot make changes to rules in a locked ruleset, you can check out a rule to a branch in your
application, make changes, and then check the rule in to your branch. You can also perform a private
checkout.

1. In the ruleform toolbar click Check out to branch, if available. Otherwise, click the arrow on the
Private edit button and select Check out to branch.
2. From the Branch list, select a branch and click Check out to branch.
 The system saves a copy of the rule to the selected branch ruleset and then checks it out.
3. Modify the rule as appropriate.
4. Click Save.
5. Check in the rule. For more information, see Checking in a rule.
Note: You do not have to check in your changes immediately. You can log out and return to a
checked-out rule later or click Discard to remove the rule from your personal ruleset.

If you discard the checked-out version, the original copy of the rule remains in the branch ruleset.

Performing a private edit

Viewing your checkouts and accessing bulk actions

Click the Checkouts icon in the Dev Studio header to open a list of rules checked out by your
operator. Rules are organized by type, name, and Applies To class. In the Private overlay, you can perform
the following actions:

Click any rule type to see only checked-out rules of that specific type.
Click any rule name to open the rule.
Expand any row to see all versions of the checked-out rule.
Click the Type or Name columns to sort the list.
Use the filter icon in the Type and Name columns to apply more specific filter criteria.

Open, delete, or check out multiple rules at once using bulk actions by clicking the Bulk actions link.
A list of rules checked out by your operator appears in a new window.

Discarding checked out rules in bulk

Maintain the best quality application by discarding checked out rules that are irrelevant to your
development projects. To save time, you can discard multiple rules at once by performing a bulk
action.

Opening checkouts in bulk

To open checkouts in bulk, complete the following steps:

Standard rule checkout

Checking in rules in bulk

Discarding checked out rules in bulk

Maintain the best quality application by discarding checked out rules that are irrelevant to your
development projects. To save time, you can discard multiple rules at once by performing a bulk action.

Before you begin: Check out rules that you want to edit. For more information, see Checking out a rule.

1. In the header of Dev Studio, click the Checked out records icon.
2. In the Checked out records window, click Bulk actions.
3. In the window that appears, select the check box next to one or more rules that you want to discard.
4. In the list at the bottom of the window next to the Start button, select Discard.
5. Click Start. Result: The Status column shows the results of your bulk discard.

Viewing your checkouts and accessing bulk actions

Opening checkouts in bulk

To open checkouts in bulk, complete the following steps:

1. Click the Checked out records icon in the Dev Studio header and then click Bulk actions.
2. Select the check box next to one or more rules.
3. Select Open from the list at the bottom of the window next to the Start button.
4. Click Start.
5. Wait for the lock icon to appear in the Status column next to each selected rule name.
 6. Review each opened checkout. If you do not have checkouts enabled, open the Recent Explorer to
access each checkout.

Viewing your checkouts and accessing bulk actions

Rule checkout notes

Note the following information when you are checking out rules:

A checked-in rule version can have validation errors, which can occur when ruleset prerequisites
change or a referencing rule is relocated. When you perform a standard checkout, the validation errors
appear in the rule form header. You must resolve all errors and save before you can check in any new
changes.
You cannot check out a base rule when you or another developer has a circumstance version checked
out.
You cannot check out the following rule types:
Application
Class
Ruleset version
Library
Agent
Application settings

Standard rule checkout

Rule checkout tips

You can use several features to determine that you have checked out all the rules in your application You
can also use other features to undo changes and to override the default check-in procedure.

Refer to the following list for tips about rule checkout.

Click the Checked out records icon in the Dev Studio header to view all the rules that you have
checked out.
Use the Application Development landing page to view all checked-out rules. Rules checked out using
the Private edit option do not appear in this list.
Use the restore feature to undo changes made by a checked-in version.
Use the Rule-.SetApprovalDependency activity to override the default check-in procedure.
Use the lock icon to see who has a specific rule instance checked out.
Select the View version > Checked out from [ version number ] option in the Actions menu to
view the base version of the rule that you checked out.

Standard rule checkout

Viewing your checkouts and accessing bulk actions
Restoring the earlier state of a rule

Personal ruleset
Users who have the Allow rule check out option enabled for their operator IDs can place copies of rule
instances into a personal ruleset. The name of this ruleset is the Operator ID, such as
john_sawyer@abc.com. The personal ruleset is sometimes called the private ruleset.

Personal rulesets are used in with the checkout and check in features. The system creates a personal
ruleset automatically when needed. No instance of the Rule-RuleSet-Name class exists for this ruleset.
Rules in a personal ruleset are never run by other users.

On the requestor page, the standard property pxRequestor.pxSecuritySnapshot.pxPersonalRuleSetName

identifies the personal ruleset. If this property is blank, the requestor cannot check out rules.

A memory cache contains rules in your personal ruleset. The maximum size of this cache (for all developers
combined) is determined by elements in the fua node of the prconfig.xml file or by dynamic system settings.

Learning about access groups

Checking in a rule
To make your changes available to your development team after you check out and edit a rule, check in
the rule. When you check in edited or updated rules, you contribute to the efficient development of your
application and avoid errors that might occur when other developers work on the same rule.

Before you begin: Check out, and then update a rule. For more information, see Checking out a
rule.Caution: Use caution when you check in rules after you perform a private edit, because you may
overwrite changes from other developers. For more information about private check out, see Performing a
private edit.

1. In the navigation pane of Dev Studio, click Records, expand the category that contains the rule that
you want to check in, and then click the rule.
2. In the header of the form, click Check in.
3. If you perform a check in after a private edit, in the Check In window, in the Destination section,
specify where you want to save the rule:
To save a rule to an unlocked ruleset, select Ruleset, and then specify a ruleset and a ruleset
version.
To save a rule to a branch, select Branch, and then specify the branch.
Note: Checking in a private edit to a branch could result in loss of work if another user checks in
changes to the same rule. You receive a warning message if your check-in might result in lost work.
4. In the Check-in comments field, enter a comment that describes your changes to the rule.
5. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
6. Click Check in.

Result: If your edits do not require approval, your changes immediately affect rule resolution and run-time
behavior for all users.

Configuring the rule check-in approval process

To turn on controlled check-in for a ruleset, complete the following tasks:

Checking in rules in bulk

Save time and improve your management of the rules that you edit in your application by performing
a bulk check-in. When you perform bulk actions, you can view all of the rules that are currently
checked out in your application, and then you can check in several rules at once.

Checking out a rule to a branch

Checking out a rule

Configuring the rule check-in approval process

To turn on controlled check-in for a ruleset, complete the following tasks:

1. Enable checkout features for the ruleset by selecting the Use check-out? box on the Security tab of the
ruleset form.
2. Enable the checkout feature for each development team member by selecting the Allow rule checkout
box on the Security tab of each member's Operator ID form.
3. On the Security tab of the ruleset form, specify both key parts of the flow that is to control the rule
check-in approval process. Specify the flow's work class in the Work class used for approval process
field and the name of the flow in the Work flow to use for approvals field. Your system includes a
standard work type Work-RuleCheckIn, standard properties and activities, and a standard flow named
ApproveRuleChanges to use for this feature. You can use the standard rules as is, or copy and adapt
them.
4. Review (and override if desired) the standard decision tree named Work-RuleCheckIn.FindReviewers to
identify the work queues used in this flow. If overriding the standard rule, create the new decision tree
in the ruleset and version being developed by the team.
5. Update the access group associated with those reviewers you want participating in the rule check-in
approval process to include the standard Work-RuleCheckIn work pool in the access group's Work
Pools list.
6. Create a work queue named ReviewChanges@ org.com or others identified in the decision tree. Update the
 Operator ID data instances for each reviewer to allow them to access the work queues.
7. Associate the standard access role PegaRULES:SysAdm4 (or another role with the privilege Rule-
.UpdatePrivateRuleSets ) with each Operator ID data instance who will approve check-ins.
8. Update the standard ruleset CheckInCandidates (version 01-01-01) to identify an appropriate
prerequisite RuleSet.
9. Add this ruleset (version 01-01-01) to the access group of those developers who are to approve check-
ins.
10. For each version you want to enable with this process, select Yes in the Approval Required field on the
Versions tab of the ruleset form.

Rule check-in process

The optional rule checkin facility allows you to use a Pega Platform flow rule to manage change to your
application. Use this facility to coordinate the efforts of large development teams or to control changes
to sensitive applications.

Rule check-in process

The optional rule checkin facility allows you to use a Pega Platform flow rule to manage change to your
application. Use this facility to coordinate the efforts of large development teams or to control changes to
sensitive applications.

See Configuring the rule check-in approval process for information about setting up controlled check-in for
a ruleset.

When this facility is in force for a ruleset version, the flow starts when a developer begins rule check in.

The flow creates a work item that is routed to a work queue, waiting for an approver to review.

The approver might approve the check-in (which completes the check in), reject it (which deletes the
changed rule), or send it back to the developer for further work.

Assignments corresponding to rules awaiting evaluation are held in the ReviewChanges@org.com work queue.

Multiple rules can be associated with one work item. The flow rule notifies affected parties by email about
evaluation results.

When uploading approved rules, select the following Import Options: Compile Libraries, Overwrite Existing
Rules, Overwrite Existing Data.

You can enhance this process to meet local requirements in various ways. For example, certain empty
(dummy) activities are called by this flow; your application can override these with desired processing.

Checking in rules in bulk

Save time and improve your management of the rules that you edit in your application by performing a bulk
check-in. When you perform bulk actions, you can view all of the rules that are currently checked out in
your application, and then you can check in several rules at once.

Bulk check in supports only rules that you check out through the standard checkout procedure. For
information about checking in rules after a private checkout, see Performing a private edit.

1. In the header of Dev Studio, click the Checked out records icon.
2. In the Checked out records window, click Bulk actions.
3. In the window that appears, select the check box next to one or more rules that you want to check in.
4. In the Check-in comments field, enter a brief description of your changes.
5. Select CheckIn from the list next to the Start button at the bottom of the window.
6. Optional: To apply one prefix to all comments, in the Bulk Prefix field, enter the text, and then click
Insert.
7. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
8. Click Start. Result: The Status column shows the results of your bulk check in.

Viewing your checkouts and accessing bulk actions

Restoring the earlier state of a rule
During application development, you can undo recent changes to a rule and replace the current rule with a
previous copy, even if another developer created the newer copies.

1. Open the current version of the rule.

2. Click the History tab.
3. Click the View full history button to view a list of snapshots in a new window.
4. Details display that contains the state you want. Click the rule history button to open the older,
historical state of this rule instance. The padlock image indicates that this is not the current rule, not
that the rule is checked out to you.
5. Click the Restore button for the state that you want to make current.

Rule restoration

If a rule has been deleted but you want to re-obtain it, you can restore the rule.

Recovering a deleted rule

Rule restoration
If a rule has been deleted but you want to re-obtain it, you can restore the rule.

You can restore a rule if you have the @baseclass.ToolbarFull privilege.

Note the following:

You do not need to use the Restore operation to fall back to a rule instance that is in a lower-
numbered version. Use the Delete toolbar button to delete the current higher-numbered version or
versions that mask or override a lower-numbered version.
If you want to change the lower numbered version but the version is locked, use Save As, not
Restore, to copy — promote — an older version to the current unlocked higher version.

Restoring the earlier state of a rule

Exploring rules in your application

To ensure that your application includes all the features that your business process requires, explore rules
that define these features. By exploring rules before you define new elements of your app, you can also
avoid duplicating resources, and as a result, save time and development costs.

Finding rules by type

You can use the Records Explorer to find all instances of a specific class, or rule type. By using the
Records Explorer instead of searching, you can quickly find a rule when you know its type but do not
know its name.

Finding rules by class

You can use the Application Explorer to find rules that share the same class. By using the Application
Explorer instead of searching, you can quickly find rules that are in your application or inherited by
your application, without having to know their names.

Finding rules by name

To find sibling rules, which are rules with the same name (key parts) but different rulesets or versions,
do the following.

Finding rules by dependency

Save development time and find rules by dependency with the Referencing Rules tool. Instead of
conducting a full-content search, you can quickly locate a rule in context by tracing the relationship
between the rules in your application.

Rule versions review and comparison

 Inspecting and comparing rule versions helps you resolve merge conflicts, review and debug code, and
audit changes that a developer made while the rule was checked out.

Comparing rules by system

You can use the Rulebase Compare wizard to identify differences in the rules present on two Pega
Platform systems. For example, you can use the tool to confirm the success of a product migration
between systems, or to identify the changes needed to synchronize two systems.

Bookmarking a rule

You can use favorites to bookmark a rule so that you can quickly find it later. You can create favorites
that are visible to your operator exclusively, another operator, or all operators within a specified
access group.

Searching for a rule

Dev Studio provides full-text search for non-deprecated rules, data objects and the help system. You
can search help system topics at any time. Searching for rules or data depends on system-maintained
index files.

Reporting on rules

You can report on rules of more than one type and rules that are checked out. For reporting purposes,
searching all instances of the classes derived from the Rule- base class, or even all instances of the
Rule-Service- class, can impact performance. To provide more efficient reporting, you can create
report definitions that query the database view that corresponds to a particular class.

Viewing rule history

You can view the saved history of a rule to see when it was changed and by whom. You can also
compare the current version with a previous version or restore a previous version of a rule for testing
purposes, or if the current version is faulty.

Viewing rule versions

View rule versions by selecting Actions View versions . A dialog box appears and displays the versions
of the rule, their availability, and their circumstance. You can click an item to open the rule form.

Viewing the generated Java of a rule

After you save a rule form, you can view an approximation of the generated Java to be created by a
rule instance by selecting Actions View Java .

Viewing the XML of a rule

If you have the @baseclass.ToolbarFull privilege, you can view the XML document that comprises the
form that displays a rule instance by selecting Actions View XML .

Replacing a string in rulesets

Use the Search/Replace a String wizard to search for and replace a string wherever it appears in rules
in the entire PegaRULES database.

Finding deprecated rules in sections

Find sections that use deprecated rules by using an application update utility. Once found, these
legacy rules can be updated to newer rules.

Finding rules by type

You can use the Records Explorer to find all instances of a specific class, or rule type. By using the Records
Explorer instead of searching, you can quickly find a rule when you know its type but do not know its name.

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

2. Expand the rule categories to browse the different rule types.
3. Click a rule type to display the instances of it that are defined in your application.
 4. Review, sort, or filter the results to find your rule.
5. Click the rule to open it.

Finding rules by class

You can use the Application Explorer to find rules that share the same class. By using the Application
Explorer instead of searching, you can quickly find rules that are in your application or inherited by your
application, without having to know their names.

1. In the navigation panel of Dev Studio, click App.

2. Optional: To find rules in a specific built-on application, change the scope of the Application Explorer.
a. Click applications.
b. Select the check box next to an application name.
c. Click Apply.
3. On the Classes tab, type one or more characters to display a list of matching class names.
4. Click a class name to browse its rules and class structure.
Tip: To reset the Application Explorer to display rules in your team, clear the class name.
5. Optional: To bookmark this class, hover on the class name, and then click the Pin icon.
6. Expand subclasses and rule types, until you find the rule of interest.
7. Click the rule to open it.

Understanding class hierarchy and inheritance

Finding the class of a rule

Finding rules by name

To find sibling rules, which are rules with the same name (key parts) but different rulesets or versions, do
the following.

1. Open the rule form.

2. Select Actions View Siblings to search the entire PegaRULES database for rules that share a second
key part with the currently displayed rule. The results are displayed in a new window.

What to do next:

The Sibling rules window shows all the rules that share the same second key part as the current rule. Not
all of these are true siblings. This display is most useful for rule types with two key parts that have an
Applies To class as the first key part.

The window might include rules in rulesets you cannot access, rules that are unavailable, and
circumstanced.

Rows in the display correspond to Applies To values. Numbers in brackets show how many distinct rules
(counting siblings, versions, circumstances, and so on) are in each class.

Columns identify rulesets and versions. Each cell that contains an icon indicates that a rule of that name
and Applies To class exists, with an icon describing the rule availability.

You can do any of the following actions:

Click the Circumstanced link, which appears for a rule with circumstance verions, to display the
circumstance property and value.
Select a value in the Applies To field to change its value and click Get Related Rules to view rules
with the same second key part in other classes.
Click Legend to view a legend for this window.
Click Details to display information about the sibling rules.

Finding rules by dependency

Save development time and find rules by dependency with the Referencing Rules tool. Instead of
conducting a full-content search, you can quickly locate a rule in context by tracing the relationship
between the rules in your application.

For example, before you remove steps from a data transform, you can use the Referencing Rules tool to
find the rules that the removal affects.

Note: Some rules do not support the Referencing Rules tool, because their references are determined at
run time.

1. Open a rule whose dependencies you want to check.

2. Click Actions View references .
3. Review the list of rules in the Referencing Rules and Referenced Rules tabs to understand the
relationships between the rules.
4. Optional: To open any of the rules listed in the tabs in their own, new tab, click the Edit icon.
5. Optional: To filter the results, on the Referencing Rules tab, click the Settings icon, and then
choose any of the following options:
To narrow the search results to the rules used only in the application, in the Rule Sets list, select
Application Only.
To include rules with the same name in the same class path, select the Show overrides check
box.
To include other versions of the rule, select the Show Versions and Circumstances check box.

Finding rules by custom field

The Find Rules by Custom Field wizard helps you generate a tailored report of rules in the system with
custom fields defined.

Note: Only Decision rules are supported by this wizard by default. You can include additional rule types in
search results by overriding the standard list view rule Rule-Obj-Class.getCategorizedRules.

1. In the header of Dev Studio, click Configure Case Management Tools Find Rules By Custom
Field .
2. Filter the search results based on the value of a custom field.
3. Choose which property values to include in the report that the wizard generates.
4. Review the report.

Selecting a rule in the Find Rules by Custom Field wizard

Select the rules you want to include in the search by performing one of the following actions.

Select the check box next to an individual rule type to include it in search results.
Select the check box next to a rule category to include a group of rule types in search results.

Next: Setting filters

Finding rules by custom field

Find Rules by Custom Field Wizard - Step 2

Setting filters in the Find Rules by Custom Field wizard

Before you begin:

Enter criteria in this step to filter results based on the value of a custom field. For example, you can find all
rules with an applies to class name that starts with Rule-Obj or a ruleset name that contains the string
customer.

1. Select a label from the Field menu of the custom field to evaluate. This list is populated by values in
the pr_index_customfields database table. If you do not see a custom field in the list, it must be
exposed as a column.
2. Select a comparison technique from the Condition menu.
3. Enter a string in the Value field to compare it with the value of the custom field selected in the Field
menu.
4. Add rows to define additional criteria or delete rows to remove them.
5. In the Filter Logic (Advanced) section, specify the search criteria order of operations. Each row in the
Filter by Custom Fields section is labeled by a letter. Enter a logical string using these letters,
 parentheses, and keywords AND, OR, NOT; for example, (A AND B) OR C. If no logical string is
specified, the system uses AND to join all search criteria together.

What to do next:

Previous: Selecting a rule Next: Selecting fields

Planning for property optimization

Find Rules by Custom Field Wizard - Step 3

Selecting fields in the Find Rules by Custom Field wizard

Include additional properties in the generated report. The selections you make here only augment the
returned results; they do not filter them.

Select the check box next to the property names to include as columns in the final report. You must select
at least one property. As a best practice, include the Rule Type property to help organize results.

Previous: Setting filters Next: Viewing the report

Find Rules by Custom Field Wizard - Step 4

Viewing the report in the Find Rules by Custom Field wizard

Review the list of rules matching the custom field search criteria. You can expand the report to look at
individual items or view the full results offline in Excel.

Results are limited to 1000. Use more specific filter criteria to help isolate results.

Previous: Selecting fields

Rule versions review and comparison

Inspecting and comparing rule versions helps you resolve merge conflicts, review and debug code, and
audit changes that a developer made while the rule was checked out.

For example, you can compare the rule that you currently work on with previously checked out versions of
the rule, branched versions, or the same rule in other ruleset versions.

Depending on your needs, you can inspect and compare rules in Pega Platform in the following ways:

Viewing changes to a specific rule on the History tab of the rule

View changes to a rule by reviewing different versions of the rule.

For more information, see Viewing changes to a specific rule.

Viewing versions of a rule on the Actions menu on a rule form

View differences between the current rule and a selected version and modify your version of the rule.

For more information, see Comparing rule versions.

Comparing rules and rule versions with the Compare Rules tool
Compare two different rules or two versions of a rule. The tool displays results in a user- friendly, color-
coded way. You also can use the tool to export the results to a Microsoft Excel spreadsheet.

You can compare rules of the following types:

 Activity
Data Transform
Function
Validate
Other technical rules that are text, such as the text files, JSP, and HTML rules.

For more information, see Comparing rules and rule versions with the Compare Rules tool.

Viewing changes to a specific rule

Get quick and full insight into the changes to a rule by reviewing different versions of the rule on the
History tab of the rule.

Comparing rule versions

Compare rule versions to resolve merge conflicts, debug code, and audit changes that application
developers made during rule check out. You can compare a rule with versions of the rule from before
the rule check out, with the branched versions, or with the same rule in other ruleset versions.

Comparing rules and rule versions with the Compare Rules tool

Apply the Compare Rules tool to two different rules or two versions of the same rule to identify and
review changes between rules. The side-by-side comparison lets you quickly find the additions,
deletions, or value changes that have occurred between two versions of a rule.

Viewing changes to a specific rule

Get quick and full insight into the changes to a rule by reviewing different versions of the rule on the
History tab of the rule.

1. Open the rule that you want to compare.

For more information, see Exploring rules in your application.

2. On the rule form, click the History tab.

3. In the History details section, click View full history.
4. In the new window, click History for All Versions to display all versions of the rule.
5. In the list that appears, select the Compare check box for each version of the rule that you want to
compare.
Note: If the current rule is checked out, the Compare With Checked Out button appears.
6. If the current rule is checked out, to compare a rule version with the checked out version, select a
version, and then click Compare With Checked Out.
7. In the Differences Found report, select a rule to view the differences between the rule versions.

Comparing rule versions

Compare rule versions to resolve merge conflicts, debug code, and audit changes that application
developers made during rule check out. You can compare a rule with versions of the rule from before the
rule check out, with the branched versions, or with the same rule in other ruleset versions.

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

2. Expand the category that stores your rule, and then select a subcategory. For example: Click
Process, and then click Service Level Agreement.
3. In the list of rules, click the name of the rule for which you want to run the comparison.
4. In the header of the rule form, click Actions.
5. Click View versions, and then select the version of the rule that you want to compare with the current
rule.
6. View the list of differences between the current rule and the compared version.
For the current rule, each list entry shows:
The type of changes.
The name of the changed page or property.
For modifications, the former and current values.
7. If you review rules properties that store code, use a compare tool that provides a detailed view of
changes between versions.
a. Click Compare text on a difference that you want to examine to view all the changes between
 versions.
Tip: You can move to a specific change by clicking the drop-down arrow, and navigate between
multiple changes by clicking the arrows.
b. Optional: To make changes to the current version of the file, you can edit, add, or remove text.
c. Optional: To replace a change in the currently edited rule with the version of the rule that you
use in comparison, click the Revert chunk icon next to the change.
d. Optional: To replace all your changes with the version of the rule that you are comparing to,
click the Undo all changes icon.
e. After you review the changes, click Done.
8. Click the entry on the list to highlight the tab and element with the change on the current rule form.
9. Optional: To see additional information about page and property changes, expand a list entry.
10. If you make changes to the current rule in this view, click Save changes to compare your revisions.
Note: If the Save changes option is not visible, it means that you do not have permission to make
changes to the rule. To make and save changes to the rule, exit the Compare view and either check
out the rule or save it into a branch.
11. Optional: To compare the current rule with another version, select the other version from the list in
the Compare Rule header. The view is refreshed with the revised change information.
12. Click Exit compare to return to the rule form.

Comparing rules and rule versions with the Compare Rules tool
Apply the Compare Rules tool to two different rules or two versions of the same rule to identify and review
changes between rules. The side-by-side comparison lets you quickly find the additions, deletions, or value
changes that have occurred between two versions of a rule.

1. In the header of Dev Studio, click Configure System Refactor Rules .

2. Click Compare Rules.
3. In the Instance #1 section, specify the first rule by providing the following information:
a. In the Rule Name field, enter the name of the rule that you want to compare.
b. In the Rule Type field, click the displayed rule type and select a value from the list.
c. In the Applies To field, select the class that contains the rule.
d. In the RuleSet field, select the ruleset that contains the rule.
e. In the Version field, select the ruleset version that contains the rule.
f. Click Find.
4. In the list of rules that appears, mark the Select field of the first rule that you want to compare.
5. In the Instance #2 section of the new panel, select the second rule to compare by performing one of
the following actions:
If the second rule instance that you want to compare is in the list, to select it, click the button
beside the rule name.
If the second rule instance that you want to compare is not in the list, in the new panel, repeat
actions from step 3, and then, in the list of rules that appears, mark the Select field of the
second rule that you want to compare.
6. Click Compare >> to generate the Differences Found report.
7. In a selected column of the report, click a row entry that has a change to display the Comparison of
rules form.
The form displays the first selected rule in the left column and the second rule in the right column.

The differences are color-coded:

Yellow
The values have changed in the two selected instances.
Green
At least one property value in the second rule is not present in the first rule. The first selected
rule is presumed to be the source instance. Consequently, the changes highlighted in green are
considered additions.
Red
At least one property with values in the first rule is not present in the second rule. The first
selected rule is presumed to be the source instance. Consequently, these changes are deletions.

If the screen displays code that includes more than one change, you can move among changes by
clicking the left and right arrow keys at the top of the screen. You can also use the search field to
locate a specific text string.

Browse the changes by using the scroll bars at the right of each column. Each scroll bar controls both
 columns, which move together to maintain the relationship between the material displayed from each
rule instance.

8. Optional: To save the comparison results to a Microsoft Excel spreadsheet, click Export to Excel.

Comparing rules by system

You can use the Rulebase Compare wizard to identify differences in the rules present on two Pega Platform
systems. For example, you can use the tool to confirm the success of a product migration between systems,
or to identify the changes needed to synchronize two systems.

Starting the tool

Select Configure System Refactor RuleSets Rulebase Compare to start the wizard. For instructions on
the form, see Using the Rulebase Compare tool.

You specify the target system and the RuleSet or a Rule-Admin-Product rule to compare. The same RuleSet
or Rule-Admin-Product must be on both systems. The comparison processing is performed on the system on
which you are running the Rulebase Compare wizard.

1. Using the Rulebase Compare wizard — Step 1: Enter System Info

Use this wizard form to specify the target system for the rule base comparison.

2. Using the Rulebase Compare wizard — Step 2: Select Instances

Use this wizard form to specify the ruleset or product that defines the set of rules you wish to
compare.

3. Using the Rulebase Compare wizard - Step 3: Display Summary

The Parameter Review form displays your target system specification and the rulesets or product rule
you have chosen to compare.

4. Using the Rulebase Compare wizard — Step 4: Display Report

The Synchronization Report lists the rules, rulesets, and ruleset versions in which differences were
found between the source and target systems. For each rule the wizard identifies the action to be
performed on the target system to make it match the source system.

Managing your Pega Platform database

Using the Rulebase Compare wizard — Step 1: Enter System

Info
Use this wizard form to specify the target system for the rule base comparison.

Complete the following fields to specify the system you want to compare to your current system.

Field Description

Select a
If you previously saved a target server definition, select it from the drop-down.
System

Host
Target server host name.
Name

Port The TCPI/IP port number for SOAP connections on the target server. Often this is port 80.

Context
Target server context root name for the Pega Platform application.
Root

HTTPS? Select if the port requires an HTTPS (Secure Socket Layer) connection.

Click to save this system specification for future use. Saved specifications appear in the
 Save
Field Select a System drop-down the next time you use this wizard.
Description
Username Enter a valid operator ID for the target server.

Password Enter the user password for the operator ID you specified.

Next >> Click to continue to the next step of the wizard.

Cancel Click to exit the wizard.

Using the Rulebase Compare wizard — Step 2: Select Instances

Use this wizard form to specify the ruleset or product that defines the set of rules you wish to compare.

Note: If you are comparing products, make sure both product rules you are comparing include all the
rulesets that you want to compare.
Field Description

Specify
Collection Select the type of rule collection you want to compare: RuleSet or Rule-Admin-Product.
Method

Select Rule
Admin
If you selected Rule-Admin-Product as the Collection Method, complete the following fields:
Product
Parameters

Select the product rule on the current system that you want to compare with the target
Name
system.

Version Select the version of that Rule Admin Product that you want to compare.

Select
RuleSet If you selected RuleSet as the Collection Method, complete the following fields:
Parameters

Click the insert row icon to add a row of ruleset parameters. Add a row for each ruleset
you want to include in the comparison.

RuleSet Select the name of the ruleset on the current system that you want to compare to the
Name target system. Choose a ruleset that is present in both systems.

Minimum
Select the minimum and maximum ruleset versions of the ruleset you have selected to
Version,
compare with the target system. The version range must match ruleset versions on the
Maximum
target system. If you do not specify a range, all versions are assumed.
Version

Using the Rulebase Compare wizard - Step 3: Display Summary

The Parameter Review form displays your target system specification and the rulesets or product rule you
have chosen to compare.

Review this information to make sure you are performing the comparison you intend to.

Using the Rulebase Compare wizard — Step 4: Display Report

The Synchronization Report lists the rules, rulesets, and ruleset versions in which differences were found
between the source and target systems. For each rule the wizard identifies the action to be performed on
the target system to make it match the source system.

Results
The wizard identifies the following types of actions:
 Add – Rules that appear on the source system but that are missing on the target system. Add these
rules to the target system to match the source system. The system determines additions and deletions
by comparing values of pzInsKey , the permanent handle of a rule.

Delete– Rules that are not on the source system but that are found on the target system. Delete these
rules from the target system to match the source system.
Update – Rules that have a different time stamp ( pxUpdateDateTime ) on the source system than on the
target system. The wizard only identifies a difference in the update times between the systems for
these rules; the report does not indicate which is more recent. Compare these rules on the two
systems to determine whether you want to preserve the change in the most recently updated rule or
use the older rule without the change.

Do not assume that rules with the most recent pxUpdateDateTime values correspond to the highest
version. Rules in any version can be updated at any time.

Click Export to Excel to save this listing in a spreadsheet.

Bookmarking a rule
You can use favorites to bookmark a rule so that you can quickly find it later. You can create favorites that
are visible to your operator exclusively, another operator, or all operators within a specified access group.

Before you begin:

Make sure that the rule you are adding as a favorite is not a checkout.
Make sure that you have opened the correct version of the rule to add as a favorite.

For example, a rule can have a base version and 50 circumstanced versions, one for each state in the
United States. You can add the Vermont instance as a favorite to Doug Smith and the California
instance as a favorite to Belle Cruise, respectively.

1. In the Actions menu of the rule form header, click Add to Favorites.
2. Enter text in the Label field that distinguishes this favorite from other delegated rules.
The value you specify appears in the Favorite Explorer and the operator menu in Dev Studio.
3. In the Add to drop-down list, indicate who can access this favorite:
My Personal: Visible to your operator only.
My Access Group: Visible to all operators in your current access group.
Other Access Groups: Visible to operators in the access group you specify.
Other User Personal: Visible to the specified operator ID only.
4. Select an option to indicate how the system finds this favorite:
Open the highest version : Rule resolution is used to find and open the delegated rule.
Always open this version : The exact version used to create the favorite is opened, even if
other instances exist in a higher ruleset version or class.
These radio buttons appear when a rule supports multiple versions.
5. Click Submit.

What to do next: While you can no longer delegate rules by using favorites, you can use the
pyCMDelegatedRules harness in the Case Manager portal to view rules that were previously delegated
using the Add to favorites action.

Searching for a rule

Dev Studio provides full-text search for non-deprecated rules, data objects and the help system. You can
search help system topics at any time. Searching for rules or data depends on system-maintained index
files.

1. To start a search perform one of the following actions:

Enter one or more terms (keywords) into the search text field and press Enter.
Leave the search text field empty and press Enter to see a list of rules recently updated by your
operator.
Click the Tick icon next to the search text field to see a list of rules that are checked out by your
operator.

What to do next:
Use the following drop-down lists to control how results are displayed:

Table 1

Menu Option Result

Only return instances of classes

Result type Rules derived from the Rule– base
class.

Only return instances of classes

Data derived from the Data– base
class.

Return results for all record

Rules and Data
types.

Only return topics available in

Help Topics
the Pega Platform Help System.

Evaluate the pyRuleName

property for Rule– instances,
Search Type Name the pxInsName for Data–
instances, and Help topic titles
when looking for a match.

In addition to record names and

help topic titles, evaluate
All Content record data (XML) and bodies of
help topics when looking for
match.

Return results based on words

that match any part of for the
Match Criteria Contains
entered term(s), including in the
middle of words.

Return results based on words

Starts With that begin with the entered
term(s).

Return results based on words

Exact Match that exactly match the entered
term(s).

Only evaluate records in your

Scope My Current Application current application when
looking for a match.

Evaluate records in your entire

All Applications application stack when looking
for a match.
Note:

By default, matches include both rules and data instances.

Changes to filtering options are remembered only for the duration of the session.

The Search tool does not search work items.

Rule– , Data– and other matches are ranked by Elasticsearch’s default relevancy ranking, based on
factors such as the number of times that the search term appears in the object.

Perform advanced searches:

The search capability is implemented using robust, fault-tolerant Elasticsearch technology for use in
distributed environments. Elasticsearch will detect and remove failed nodes in a cluster, automatically
replicating and reorganizing nodes as needed.

Note: To take advantage of Elasticsearch distributed architecture, multiple nodes should be

configured to host Elasticsearch index files. See Full text search.

The search terms entered are converted into the appropriate Elasticsearch query syntax based on the
search method chosen. You can enter more advanced Elasticsearch query syntax to perform complex
searches.

The following general rules apply to searches:

Elasticsearch uses the ( * ) asterisk as a wildcard to match zero or more characters, and the ( ? )
question mark as a wildcard to match any single character. The * character is automatically
added before and after search terms when you use the Starts With (term * ) or Contains ( * term * )
search method , and you do not have to manually enter them.

To search for a rule based on its Applies To class and name, select the All Content option for Search
Type (since pyRuleName does not contain the class name), and enter a search such as class-
name*rule-name or class-name. For example, to see the version of the pyLabel property within the Work-
class, search for Work-*pyLabel .

If you enter two or more words, they are treated by default as a single phrase during search.

Your search string may contain characters - _ % or @. Your search string may contain a ! but
escaped with a preceding \ character. Searches with any of these characters are exact match
only. Searches involving other special characters such as ( [ { }]} ^ ~ * # : \ | are not supported.

When a search string is enclosed in quotes, the selected search method is ignored, and an Exact
Match is always performed using the exact text within quotes.

Use the special syntax property-name:value to search for instances with a specific property value. Set
the Search Type option to Content for this type of search. Enter an exact property name, including
capitalization. The searched value cannot contain any special characters. Instances whose value
starts with the value entered are matched. For example, pxObjClass:Rule-Obj-Flow returns a list of all
Rule-Obj-Flow and Rule-Obj-FlowAction rules.
You can enter more advanced Elasticsearch queries. For information about the Elasticsearch
query syntax, go to the Elasticsearch website at elastic.co.

When entering advanced syntax, select Exact Match as the Search Method. For example, you
can use the Boolean operators AND, OR, and NOT to search for combinations of multiple terms and
phrases. Capitalize the Boolean operators to distinguish them from the terms or phrases being
combined. You can use parentheses to group conditions. See the examples below.

Table 2

Syntax sent to
Entered text Search method Match returned if
Elasticsearch

Exact word abc exists in

abc Exact Match abc
searched text.

One or more words

abc Starts With abc* beginning with abc exist
in searched text.

One or more words

abc Contains *abc* containing abc exist in
searched text.

Exact phrase abc def

abc def Exact Match abc def
exists in searched text.

One or more phrases

starting with the exact
abc def Starts With abc def* word abc followed by a
word starting with def
 Syntax sent to exists in searched text.
Entered text Search method TheMatch
stringreturned if
abc def exists
Elasticsearch
abc def Contains *abc def*
anywhere in searched
text.

Exact word abc:01-01-01

“abc:01-01-01” Any abc:01-01-01
exists in searched text.

Exact word abc:01-01-01

abc\:def Exact Match abc\:def
exists in searched text.

One or more words

abc\:def Starts With abc\:def* beginning with abc:def
exist in searched text.

One or more words

abc\:def Contains *abc\:def* containing abc:def exists
in searched text.

Either the exact word

abc OR def Exact Match abc OR def abcor the exact word def
exists in searched text.

Either one or more

words beginning with
abc* OR *def* Exact Match abc* OR *def* abc or one or more
words containing def
exists in searched text.

Both the exact word abc

abc AND def Exact Match abc AND def and the exact word def
exists in searched text.

Both one or more

words beginning with
abc and one or more
abc AND def Exact Match abc* AND def*
words beginning with
def exists in searched
text.

One or more words

starting with abc exists
in searched text, the
string def may also exist
(+abc* *def*) NOT ghi* Any (+abc* *def*) NOT ghi* anywhere within the
searched text, and no
words starting with ghi
exist in the searched
text.

Configuring system settings

Finding deprecated rules in sections

Reporting on rules
You can report on rules of more than one type and rules that are checked out. For reporting purposes,
searching all instances of the classes derived from the Rule- base class, or even all instances of the Rule-
Service- class, can impact performance. To provide more efficient reporting, you can create report
definitions that query the database view that corresponds to a particular class.

To report on rules of more than one type, create a report definition rule with Data-Rule-Summary as
the Apply to class. The properties that you use for selection criteria must be stored as exposed
columns of the PegaRULES database view that corresponds to the Data-Rule-Summary class.
To report on rules that are checked out, create a report definition rule with Data-Rule-Locking as the
Apply to class.
 Viewing the heat map

You can view a heat map that shows in the number of rules in each category, broken down by rule
type. The size of each box reflects the number of rules of a single rule type. Complete the following
steps.

Viewing and running inventory reports

Inventory reports are not associated with a specific application's work items, assignments, or
processing. You can run reports for which the Applies To key part is a class derived from the System-,
Data-, or Rule- base classes.

Reviewing exposed properties

To enhance record selection operations for reporting, certain single value properties are stored as
exposed columns in an application. You can review which properties are exposed in your appliction.

Viewing and running inventory reports

Viewing the heat map

You can view a heat map that shows in the number of rules in each category, broken down by rule type.
The size of each box reflects the number of rules of a single rule type. Complete the following steps.

1. In Dev Studio, click Configure Application Inventory Heat Map .

2. In the Shaded by list, select an option to graphically shade the heat map by number of recently
updated rules, number of warnings, or number of rules checked out per category. The darker the
shade, the higher the number of the filtered type that is found in that rule type.
3. Click the Filter button to add or remove rulesets and rule categories from the heat map.
4. Left-click a rule type on the heat map top open a report that displays all rules of the selected type in
the selected type in the application.
5. Right-click a rule type on the heat map to open a report that displays all rules of the selected type in
the application that match the filter selected for the recently updated rules, the number of warnings,
and the number of rules checked out per category.

Managing application inventory

Viewing and running inventory reports

Inventory reports are not associated with a specific application's work items, assignments, or processing.
You can run reports for which the Applies To key part is a class derived from the System-, Data-, or Rule-
base classes.

1. To view inventory reports, click Configure Application Inventory Inventory Reports .

2. Click the report name to open its rule form, and specify the appropriate information.
3. To run the report, click Run from the Actions menu.

Reporting on rules

Reviewing exposed properties

To enhance record selection operations for reporting, certain single value properties are stored as exposed
columns in an application. You can review which properties are exposed in your appliction.

You can use exposed properties to search for archived cases. For more information, see Reviewing archived
case data

1. Click Configure > Data Model > Classes & Properties > Database Class Mappings.
2. Locate your class in the Database Class Mappings table.
3. In your class's row, click the number in the Exposed/Mapped column to view exposed properties for
that class.

Reporting
Viewing rule history
You can view the saved history of a rule to see when it was changed and by whom. You can also compare
the current version with a previous version or restore a previous version of a rule for testing purposes, or if
the current version is faulty.

1. Open a rule form, click the History tab, and then click View full history.
2. Click the Pencil icon next to a history record to see a previous version this rule instance.
3. Optional: To make an older copy of the rule become the current copy, click Restore on the rule form.
For more information, see Restoring the earlier state of a rule.
4. Optional: To compare rule versions, select any two versions of the rule from the table and click
Compare. For more information, see Comparing rule versions on the History tab.
5. Click History For All Versions to see the history of all versions of this rule with the same name,
ruleset, and circumstance qualification, if any. To return to the original display that show showing only
the history of this open rule, click History of Version NN-NN-NN.
Note: The History For All Versions button is not displayed for class rules ( Rule-Obj-Class rule type)
and a few other rule types. Class rules have an associated version field, but do not belong to a single
specific ruleset version.

Viewing rule versions

View rule versions by selecting Actions View versions . A dialog box appears and displays the versions of
the rule, their availability, and their circumstance. You can click an item to open the rule form.

You cannot view versions on rules that are not versioned, such as applications, classes, and rulesets.

Viewing the generated Java of a rule

After you save a rule form, you can view an approximation of the generated Java to be created by a rule
instance by selecting Actions View Java .

You can view Java if you have the @baseclass.ToolbarFull privilege, and you can view Java for certain rules,
including activities, when rules, and stream rules.

Viewing the XML of a rule

If you have the @baseclass.ToolbarFull privilege, you can view the XML document that comprises the form
that displays a rule instance by selecting Actions View XML .

You can view the XML document to assist in debugging so that you can identify the property names and the
handle for each property that is referenced in the form. Note: If you have modified and saved the rule or
data form, this information might be out of date. To see updated information, close the form, open the
same rule or data type again, and select Actions View XML again.

Finding the class of a rule

Replacing a string in rulesets

Use the Search/Replace a String wizard to search for and replace a string wherever it appears in rules in
the entire PegaRULES database.

You can search and replace the string in:

All rulesets in the system

The rulesets included in your ruleset list.
A single ruleset or set of selected rulesets

The wizard reports any locked rulesets or rules that are checked out before performing the replacement,
and any class names that might be affected. A list of qualifying rules appears for your review before any
rules are altered.

The wizard uses the full-text search to reduce search time and increase accuracy. If full-text search for
rules not enabled for your system, and you do not limit the scope of the process to certain rulesets, the
process can take many minutes to complete.

Use this powerful tool with care. Rules updated by this wizard are not automatically revalidated and may
become invalid as a result of string replacement. As a precaution, export the rulesets in to a .zip archive or
back up the entire PegaRULES database before using this tool. The .zip archive can serve as a backup if the
results of the wizard are not satisfactory.

Select Configure > System > Refactor > Rules > Search/Replace a String to start the tool.

In changing a string, the utility looks for the specified string anywhere in any value within any rule within
the search scope, and gives you the option to select the rules you want to modify. To specify the string to
replace for the selected rules, it will replace the original string with the replacement string.

Strings are replaced only in rules, not in work items, assignments, attachments, or other objects. If string
replacement changes rules in subclasses of Work- or any of its properties, the subsequent processing of
those work items in those classes may encounter problems.

Finding deprecated rules in sections

Find sections that use deprecated rules by using an application update utility. Once found, these legacy
rules can be updated to newer rules.

Your application might contain sections that use legacy rules or images. Legacy rules and images have
been deprecated or updated with newer rules. Update or refactor legacy rules to use the latest Platform
rules. You can search for legacy rules by using the Application Update Utilities. Note: Images are found
using index references and the results are compared using rules names. This means that even after you fix
an image in a section, the rule may still be listed in the report

1. Click Configure System Release Update Update tools .

2. Click the List rules using legacy rules link.
3. From the list of rules, select a rule to open it. From here you can update or refactor the rule.

Moving applications between systems

Importing the legacy ruleset from the Resource Kit

Delegating a rule or data type

To delegate a rule or data type to enable your business line to configure simple application logic without
involvement from IT, complete the following steps.

1. Open the rule or data type that you want to delegate.

2. From the Actions menu, click Delegate.
3. Select how the end user will interact with the delegated rule.

The options that are displayed depend on the rule or data type that is being delegated.

Manage content – Users can modify the content of decision tables, map values, paragraphs,
and correspondence rules.
Manage content and modify table – For map values, users can add, modify, or delete rows
and columns in the map value table in addition to modifying contents.
Manage data records – For data types, users can add, modify, or delete data entries for the
data type.
Manage SLA – For SLAs, users can configure goals, deadlines, and escalation actions.Note: You
cannot delegate SLAs on which service levels are calculated by the value of a property.Note: If
you later modify a delegated SLA in Dev Studio to have service levels calculated by the value of a
property, users cannot modify the Days or hh:mm fields or select the Calculate using
business days check box for the Goal, Deadline, or Passed Deadline sections.Note: When
users modify SLAs in the Case Manager, they can select only Notify Manager or Notify
Assignee as escalation actions. If you change the escalation action in Dev Studio to anything
other than these actions, users cannot modify escalation actions.
4. In the Delegate to access group drop-down list, press the Down arrow and select the access group
to which you want to delegate the rule or data type.
5. In the Title field, enter a title for the delegated rule or data type.
6. In the Detailed Description field, enter detailed information about the delegated rule or data type.
This text is displayed to the user.
 Provide information about how the delegated rule or data type will affect the application. For example,
"The logic in this delegated decision table determines whether a travel request required additional
manager approval. Changing the logic in this decision table may affect all subsequent travel requests
submitted in this application."
7. Click Delegate.

Delegating a data type

You can delegate a data type so that other users can modify records in local data storage tables.

Rule and data type delegation

You can delegate a paragraph, decision table, data type (configured for local storage), map value,
correspondence, or service-level agreement (SLA), including circumstance types, to your business line
to bring less-technical stakeholders closer to your application development. Users access these
delegated rules and data types from the Case Manager portal. Users can also access data types in App
Studio.

Prerequisites for delegating a rule or data type

Before delegating a rule or data type, ensure that you certain requirements, such as having the
appropriate permissions.

Best practices for delegating a rule or data type

To successfully delegate a rule or data type to less-technical business users, you should follow certain
best practices.

Modifying a delegated record or data type

You can modify records or data types that are delegated to you by developers. By using delegation,
you can change the functionality of your application without involving additional staff members, such
as database administrators and information technology professionals.

Configuring ruleset update behavior

You can configure when users see new ruleset lists due to changes of access groups or applications:
immediately, at the start of the next thread, or at the next session.

Rule and data type delegation

Modifying a delegated record or data type
Creating a data object

Delegating a data type

You can delegate a data type so that other users can modify records in local data storage tables.

1. Click Turn editing on.

2. In the navigation panel, click Data to view the list of current data types in your application.
3. Select the data type that you want to delegate.
4. On the Settings tab, select the Allow selected users to modify records check box.
5. Select the role of the users that you want to let modify records.
6. Click Done.

Modifying a delegated record or data type

Creating a data object

Rule and data type delegation

You can delegate a paragraph, decision table, data type (configured for local storage), map value,
correspondence, or service-level agreement (SLA), including circumstance types, to your business line to
bring less-technical stakeholders closer to your application development. Users access these delegated
rules and data types from the Case Manager portal. Users can also access data types in App Studio.

Rule delegation allows the business line to configure simple application logic without involvement from IT.
For example, you can delegate a decision table to a business line manager. The line manager views the
decision logic in a familiar environment, such as the Case Manager portal, and can update it as a stand-
alone item without knowing all of the related, technical details.

Delegating a rule or data type

Modifying a delegated record or data type
About Map Values
Decision tables

Prerequisites for delegating a rule or data type

Before delegating a rule or data type, ensure that you certain requirements, such as having the appropriate
permissions.

Ensure that the following prerequisites are met:

The rule or data type you are delegating is not a checkout.

The rule you are delegating is not in a Pega ruleset.
You have the pxCanDelegateRules privilege, which grants you the ability to delegate rules and data
types that are visible to users outside of your access group.
The rules you are delegating are in an unlocked ruleset accessible to end users.

Delegating a rule or data type

Rule and data type delegation

Best practices for delegating a rule or data type

To successfully delegate a rule or data type to less-technical business users, you should follow certain best
practices.

When you delegate rules or data types, you should:

Choose titles and descriptions that are meaningful in a business context.

Isolate delegated rules in a separate, unlocked ruleset that does not require checkins or checkouts.
This insulates the rest of your application, which typically resides in locked rulesets, from frequent
changes made by managers to other delegates.
Provide appropriate training and documentation to line managers.
If you delegate a rule or data type and then rename the class, you must re-delegate the class.

Delegating a rule or data type

Rule and data type delegation

Modifying a delegated record or data type

You can modify records or data types that are delegated to you by developers. By using delegation, you
can change the functionality of your application without involving additional staff members, such as
database administrators and information technology professionals.

1. In the left navigation pane, click Configuration.

2. To filter items by keywords, enter text in the search field.
3. Click Edit to modify a delegated item.
The type of information you can modify depends on the type of item and the options selected at the
time of delegation.
4. Click Save.

Delegating a data type

Configuring ruleset update behavior

You can configure when users see new ruleset lists due to changes of access groups or applications:
immediately, at the start of the next thread, or at the next session.

By default, a session's ruleset list changes immediately when the sessions's access group or application
changes. You can configure your server to change the ruleset list at the start of the next thread or session.
 1. Update the Authorization/RSLUpdateBehavior setting in the prconfig.xml file with the desired value.
Immediate
The default setting.
Ruleset lists are updated as application and access group changes are made.
Threadset
Ruleset lists are updated from application and access group changes at thread creation
boundaries and stay the same for the entire lifetime of the thread.
Thread creation boundaries include thread creation and thread switch events.
Fixedreq
A snapshot of the ruleset lists are taken for all available applications at login.
Fixed throughout the lifetime of the session.
If a requestor with RSL update behavior set to fixedReq spawns a child requestor, the child
requestor gets the most recent context using their parent's access group as a key.
For information on changing the prconfig.xml file, see Changing node settings by modifying the
prconfig.xml file.
For example: <env name="Authorization/RSLUpdateBehavior" value="threadset" />
2. Restart the server.

Changing node settings by modifying the prconfig.xml file

Importing the legacy ruleset from the Resource Kit

Applications that require deprecated rules that are no longer included in the Pega Platform distribution
need to import those legacy rules from the Resource Kit.

If your applications use deprecated rules that are no longer included in the Pega Platform distribution
media, you can import the legacy rules from the Pega Platform Resource Kit. The removal of these legacy
rules reduces the size of a Pega Platform installation. The smaller installation also reduces the size of the
rule database and shortens installation and upgrade time. If your application still uses legacy rules, they are
available in the PegaLegacyRules:01-01-01 in the Resource Kit on the Pega Platform media.

Note: The best practice is to refactor the existing application that references legacy rules or repackage
your application without the affected rules.

1. Import the legacy ruleset from the Resource Kit by clicking Configure Application Distribution
Import .
2. Navigate to the distribution media, select ResourceKit\Utilities\PegaLegacyRules, and then click Next.
3. Click Next on the confirmation screen. The next screen displays a list of rules that are already in the
system in a different ruleset and conflict with the legacy rules.
4. Select the check box next to the rules that you want to load. This replaces the existing rules with the
same name and can cause incompatibilities with the existing application that references those rules. If
you choose not to load the rules, the rules that reference these instances might not work correctly.
5. Click Done to complete the import process.
6. Open the Application definition.
7. Add the PegaLegacyRules:01-01-01 ruleset to the list of application rulesets, and then save the
definition.

Moving applications between systems

Finding deprecated rules in sections

Renaming classes or rulesets during an archive import

Use the Refactor on Import wizard to rename classes or rulesets in an archive as it is imported. This allows
you to integrate the imported structure into the existing hierarchy on your system. The Refactor on Import
wizard supports merging RuleSets developed by Pegasystems or others into your PegaRULES database.

The Refactor on Import wizard displays a listing of the classes in the archive and allows you to specify the
names of classes to replace the top-level and Data- classes for rules contained in the archive. On import,
the rules contained in the *.jar or *.zip file, are read into memory, renamed with your specified changes,
and then copied to the Pega Platform database. The import archive is not modified. Errors are reported on
rules that will not validate when saved, but all rules are saved to the database.

1. In the header of Dev Studio, click Configure System Refactor Rules .

2. Click Refactor on import.
 3. Select a file to import:
If the file already exists in the server ServiceExport directory, click Next.
To upload a new file, click Choose file and follow the prompts.
4. Select the name of the file you want to import, and click Next.
5. Specify new class names and optional new ruleset names to apply to each class or ruleset as they are
imported and then click Next.
Note: If the archive contains a product rule, the Refactor on Import wizard looks for a previous import
of the same Rule-Admin-Product name. If there is a previous import with the same name, the wizard
displays the refactor parameters used in the previous import as the default values for the current
import.
6. Verify that the changes are accurate and click Next.
Click ExportToExcel to create a detailed list of the rules that will be changed. You can use the
spreadsheet to evaluate the effects of renaming the class before beginning the processing.
7. Click Next.
8. Select additional rules to be changed. If the archive includes rules that the system cannot clearly
identify as a class or ruleset name, you see a list of additional rules to be changed. The check box at
the top of the column only selects the instances on the current page.
Note: For example, the name may be embedded in a Java class name, a URL string, or some other
property. These may be incidental occurrences of the class name that you do not wish to change. For
example, if you had used your organization name for the original class name, you might want to keep
the name where it appears in strings displayed in the user interface.
9. Optional: To review the additional rules outside the wizard, click Export To Excel to create a
spreadsheet of the currently displayed page or Export All To Excel to create a spreadsheet of the
entire report.
10. Review the list of all rule instances that you selected to be refactored that could not be changed
successfully. Hover over the error message in the Status column for more details on the error. To
review the status for all rules outside the wizard, click Export All To Excel.
11. Click Finish.

Result: Each use of this wizard is recorded in an instance of the Log-Refactor class, with a key identifying
the date and time of the use.

Packaging your application in a product rule

Omitting history snapshots for data types

To improve performance and manage your resources efficiently, you can choose not to take history
snapshots when you develop data types. Every time a value in a data type changes, before you implement
the change, the system takes a snapshot of the previous instance in case you need to restore the data type
to the previous state. With multiple changes, omitting the snapshot can save you time and resources.

For example, you can choose not to take the snapshot of a data type in the following scenarios:

A data type is only an additive and remains unchanged throughout your entire business process.
The frequency of updates to a data type is large, which makes snapshots less useful.
Because every snapshot is a BLOB write, high numbers of snapshots might affect performance.
You implement your custom history-saving policy.

The system stores snapshots in the History- class of a respective data type.Note: You can omit snapshots
only for data types. When you develop rules, the system takes snapshots and stores them in a related
History- class.

1. In the navigation pane of Dev Studio, click Data types.

2. Hover over a data type, and then click More View definition .
3. On the data type rule form, click the Advanced tab.
4. In the Bypass History on Save section, select True.
5. Click Save.

Result: When a value in a data type changes, the system does not take the snapshot of the initial value.

Organizing rules into classes

Understanding class hierarchy and inheritance
Creating classes
Creating a data type in Dev Studio
Referencing properties
Provide the data necessary to process your cases by referencing information in the form of properties.
When you refer to a property, your application calls a specific piece of information, such as a customer
phone number or an address.

You can reference value properties that are strings of data such as text, number, or dates. You can also
reference page properties that contain multiple value properties. For example, a page property .Customer
might include value properties .Name, .Address, and .Phone.

To refer to a property, prefix the property name with a period. For example: To reference an order
date, enter .OrderDate.
To refer to a Single Value property, enter the property name. For example: To reference a shipping
date, enter .ShippingDate .
To refer to an entry in a Value Group property, enter the Value Group name, and then the property
name in parentheses. For example: To reference a mobile phone number from a Value Group
property of phone numbers, enter .Phone(Mobile).
To refer to an entry in a Value List property, enter the Value List name, and then the index number of
the entry in the list. For example: To reference the first entry in a list of discount codes, enter
.DiscountCode(1).

Apply the same guidelines when you reference Page properties.

To refer to a Page property, enter the Page property name. For example: To reference a page with
customer contact details, enter .ContactDetails.
To refer to an entry in a Page Group property, enter the Page Group name, and then the entry in
parentheses. For example: To reference a work address in a page group of addresses, enter
.Address(Work).
To refer to a page in a Page List property, enter the Page List name, and then the page number in
parentheses. For example: To reference the third page in the page list that contains ordered items,
enter .OrderedItems(3).
To refer to a specific property on a page, enter the page name as a prefix for the property name. For
example: To reference a city in the work address, enter .Address(Work).City.

Naming conventions for properties

Creating descriptive and logical names for your properties can help you convey essential information
just by looking at the name. As a result, you speed up development of your application, promote reuse
across your application, and avoid duplicating properties that already exist in your system.

Configuring page, page group, and page list properties

To provide complete data for your cases, define properties that store related information in a form of a
page, page group, or page list. By providing properties of a page type, you organize data in your
application in a logical way, and as a result, improve application development and speed up case
resolution.

Viewing test coverage reports

Data transforms

Naming conventions for properties

Creating descriptive and logical names for your properties can help you convey essential information just
by looking at the name. As a result, you speed up development of your application, promote reuse across
your application, and avoid duplicating properties that already exist in your system.

For example, you can create CustomerName and PhoneNumber properties that clearly describe the type of
data that the properties reference.

For the names of a property, choose nouns or noun phrases that clearly describe the property. Use names
that are descriptive and meaningful, so that the contents of the property are easier to understand. For
example, LoanNumber is a good choice for a numeric account number, while LoanID is a better choice for
an alphanumeric account number. Enter the name in a camel case convention with the first letter in
uppercase and then capitalize the first letter of each additional connected word.
For clarity, follow the following guidelines:

End names for lists, that are Page List properties, with list.
End names for groups, that are Page Group properties, with group.
Because property names are case-sensitive, use only letters and digits.
Do not start property names with an underscore ( _ ) or dollar sign ($).

Standard property names

Standard property names that Pega Platform includes start with the px, py, and pz characters. Do not start
names of your properties with these prefixes. The following table describes the purpose of each of the
prefixes:

Prefix Description

Computed properties that users see on a form, but cannot directly enter or
px
change values, for example a pxCreateDateTime property.

Properties that users can explicitly enter or change, for example a pyDescription
py
property.

Properties that are reserved for internal use, for example a pzInsKey property.
pz
Users cannot see, enter, or change properties with the pz prefix.

Naming conventions for records

Naming conventions for classes
Rules in Pega Platform applications
Building logic and calculating values in your application

Configuring page, page group, and page list properties

To provide complete data for your cases, define properties that store related information in a form of a
page, page group, or page list. By providing properties of a page type, you organize data in your application
in a logical way, and as a result, improve application development and speed up case resolution.

When you create single page and page list properties, you also define how your application sources data for
the properties. To save time, you can configure your application to refer to a data page or to copy data
from a data page while providing values for properties. For greater flexibility, you can also allow users to
provide values manually.

1. In the header of Dev Studio, click Create Data Model Property .

2. In the Label field, enter a short description for the property.
3. Optional: To manually set the name key part of your record to a value that is different from the
default, in the Identifier field, click Edit, and then update the name.
The default value of this field is To be determined. The system automatically populates the field with a
read-only value based on the sentence that you enter in the Label field. The system ignores spaces
and special characters.
4. In the Context section, select the application layer in which you want to store the record.
5. In the Apply to field, select the class to which this record applies.
6. In the Add to ruleset field, select the name and version number of a ruleset to contain the record.
7. Click Create and open .
8. On the General tab of the property form, in the Property type section, click Change, and then
define a property type:
To create a page, click Single Page.

Single pages contain embedded pages as values. For example, you can create a single page that
stores information about a user that creates a case, such as a user ID and an email address.

To create a page group, click Page Group.

Page group properties contain unordered groups of embedded pages. For example, you can
create a page group that stores information about work parties, and each embedded page stores
information about one work party, such as a customer or a worker.
 To create a page list, click Page List.

Page list properties contain ordered lists of embedded pages. For example, you can create a page
list that store multiple addresses of a customer.

9. In the Page definition field, enter a page class.

The page definition stores information about what is the class of each page in this list. When you
provide the page definition, the system determines what fields each page has or what rules the system
can use on pages in this list.
10. If you configure a single page or page list property, in the Data access section, define how property
sources values:
Choices Actions

Users provide
data manually at Select Manual.
run time

a. Select Refer to a data page .

b. Optional: If you configure a PageList, to retrieve each embedded page in
Property refers
the PageList separately, select the Load each page in this page list
to a data page
individually check box.
c. In the Data Page field, enter a data page that stores values to refer.

a. Select Copy data from a data page.

b. Optional: If you configure a PageList, to retrieve each embedded page in
the PageList separately, select the Load each page in this page list
Property copies
individually check box.
data from a data
c. In the Data Page field, enter a data page that stores values to copy.
page
d. Optional: To copy only selected information from the data page, in the
Optional Data Mapping field, enter a data transform that determines what
information the system copies.
11. Click Save.

Configuring a data transform

Managing relevant records and components

Save time during application development by reusing elements such as relevant records and components.

Relevant records for rule reuse

Relevant records are rules that Pega Platform automatically marks for reuse in App Studio, or that
application developers manually designate for reuse in Dev Studio. By using relevant records, you
configure your application with developer-approved rules, improve its quality, and reduce
development time.

Installing components

Install a component to make a reusable feature available to applications on your system.

Relevant records for rule reuse

Relevant records are rules that Pega Platform automatically marks for reuse in App Studio, or that
application developers manually designate for reuse in Dev Studio. By using relevant records, you
configure your application with developer-approved rules, improve its quality, and reduce development
time.

Relevant records creation

Typically, Pega Platform automatically manages relevant records for you. In App Studio, when you create
records, such as fields, views, processes, and user actions in the context of a case type or data type, Pega
Platform automatically marks these records as relevant.

You can also configure a rule in Dev Studio, then mark the rule as a relevant record so that the rule is
accessible to other developers from prompts in App Studio.

For example, when you configure an assignment and select an existing service-level agreement (SLA)
option in App Studio, the SLA is available in the drop-down list only if another developer first creates and
marks the SLA as a relevant record in Dev Studio.

SLAs as relevant records in App Studio

Rule types that you can manually mark as relevant records in Dev Studio include:

Properties, also known as fields

Sections, also known as views
Harnesses
Paragraphs
Correspondences
Service-level agreements
Strategies
Processes, also known as flows
User actions, also known as flow actions
Decision Tables
Notifications
Pulse Feed rules
Validate rules
When rules

Note: You can mark records that are outside classes that Pega Platform provides by default, such as
@baseclass or Work- classes.

You can manually designate records as relevant in the following ways:

Mark a rule as a relevant record in the rule form

You can mark a selected rule as relevant directly in the rule form in Dev Studio.

For more information, see Marking a record as relevant.

Add a rule as a relevant record on the Relevant records tab

You can designate a selected rule as a relevant record on the Relevant records tab in Dev Studio.

For more information, see Adding a relevant record to a specified class in your application.

You can access relevant records in App Studio, in the Data Designer or the Case Designer, when you add a
step to a process, add fields to a user view, or apply a service-level agreement.

For example, when you configure a user view for a step in a case life cycle, Pega Platform populates the
Fields and Views lists with relevant records, as shown in the figure:

Relevant records in the Fields list

Relevant records in the Views list
The functions of relevant records
Relevant records control design-time prompting and filtering in the following areas:

In case types
Relevant records for a case type can include references to properties, sections, processes, and user
actions that are explicitly important to your case.

Properties marked as relevant define the data model of the case. Processes and user actions marked
as relevant appear in prompts for case type settings to encourage reuse. Sections marked as relevant
appear as reusable sections.

In data types
Relevant records designate the most important inherited fields for a data type. Relevant records can
include fields that are defined for the class of the data type and fields inherited from parent classes.
In condition builders
When you build conditions in a condition builder in App Studio, or on the Condition tab of a when rule
in Dev Studio, you see a list of fields and when conditions that you can use in your custom condition.
The list populates with relevant records. If a record is not in the list, you can add it to relevant records
in your application.

For more information, see Adding a relevant record to a specified class in your application and
Defining conditions in the condition builder.

In proposition filters
When you use properties, strategies, and when rules as proposition filter conditions, you designate
these elements as relevant records for your primary context class, which by default is the Customer
class.

For more information, see About Proposition Filter rules.

Creating new properties on the Properties tab of a strategy or a proposition automatically marks the
properties as relevant records. You must manually add strategies and when rules to the list of relevant
records for a specific class.

For more information, see Managing relevant records.

Relevant records in Data Designer

The Data Designer displays properties for the selected data type that the system marks as relevant
records. In Dev Studio and App Studio, use the filtering options to show reusable fields, which are relevant
records defined elsewhere in the selected data type's inheritance path, and to show internal system fields.

The Dev Studio Data Designer provides the Show inherited and Show relevant records filtering
options.

The Data Designer in App Studio displays only relevant records (properties) for the selected data type, with
an option to display or hide relevant fields defined in inherited classes.

New fields that you add to the data types are automatically marked as relevant records as shown in the
figure.

Data Designer with relevant records

Relevant records in Case Designer

You can access relevant records from several locations in Case Designer:

From the Data model tab

The Data model tab displays properties for the selected case type that the system marks as relevant.
Use the filtering options to display reusable fields or system fields.

A Data model tab with relevant records

From the Workflow tab

On the Workflow tab, the view configuration window for a selected assignment displays records for
the selected case type that the system marks as relevant. The Fields list displays fields (properties)
that are configured on the current case type and marked as relevant records. The Views list displays
views that are configured on the current case type and marked as relevant records.

The system automatically marks new fields that you add to a form as relevant for that case type.

A Workflow tab showing relevant records

On the Workflow tab, the More section of the step menu displays flows and flow actions that the
system marks as relevant records from the Process and User actions lists, respectively.

The system automatically adds new user actions that you add to the case to the relevant records for
that case type as shown in the figure.

The flows and flow actions with relevant records

From the Views tab
The Views tab displays the views (sections) that the system marks as relevant records for the current
case type.

The system automatically marks any additional views that you create as relevant to the current case
type, as shown in the figure.

The Views tab with relevant records

For relevant training materials, see the Promoting rule reuse with relevant records module and the
Designating a relevant record challenge on Pega Academy.

Managing relevant records

Speed up your application development by curating records that you need to include in your case
types and data types. Relevant records control design-time prompting and filtering in several areas of
App Studio, and as a result, reduce time-consuming searching through unrelated records in your
cases.

Marking a record as relevant

To save resources and speed up application development, promote reuse in data types and case types
by marking a rule as a relevant record. Relevant records control design-time filtering options in case
types and data types in App Studio. As a result, when you create an application, you receive a set of
relevant options, instead of an extensive or incomplete selection of choices.

Adding a relevant record to a specified class in your application

Expand the library of relevant records by adding records and classes that are most likely to be reused
for a case or data type.

Marking relevant records as active or inactive

Make a record available or unavailable in App Studio by marking the record as active or inactive. By
marking certain records as inactive you can narrow down the list of relevant records to suit the current
implementation context best, without the need to delete any records from your application.

Security of relevant records

You can define a list of relevant records in one or more case types or data types in your application
before you deliver the application to customers or other development teams. By updating a related
when rule, you can enable or disable certain access groups to add or remove relevant record entries
from a class.

Managing relevant records

Speed up your application development by curating records that you need to include in your case types and
data types. Relevant records control design-time prompting and filtering in several areas of App Studio, and
as a result, reduce time-consuming searching through unrelated records in your cases.

For example, in an insurance application, you can mark a value field of an insured object as a relevant
record so that it is available to all child classes, such as a class that stores records for jewelry insurance or
vehicle insurance case types.

1. In the header of Dev Studio, click Configure Application Inventory Relevant Records .
2. In the Class Name field, enter the class of a case type or data type for which you want to display
relevant records.
Note: By default, the system displays only active relevant records for the selected class. For more
information, see Marking relevant records as active or inactive.
3. Manage the records by performing any of the following actions:
To display inactive records for the specified class, select the Show inactive relevant records
for the class check box.
To display records that the current class inherits through the class hierarchy, select the Show
inherited relevant records for the class check box.Note: The Mark relevant at column
shows at which class level the particular record is relevant.
To mark a record as active or inactive for the current class, click the Actions icon, and then
select an option that meets your need. For example, select Mark active for current class.
4. Click Submit.

App Studio overview

Rules in Pega Platform applications
Configuring a data model for a case
Views for cases

Marking a record as relevant

To save resources and speed up application development, promote reuse in data types and case types by
marking a rule as a relevant record. Relevant records control design-time filtering options in case types and
data types in App Studio. As a result, when you create an application, you receive a set of relevant options,
instead of an extensive or incomplete selection of choices.

For example, in a banking application, you can mark a property that holds an interest rate as a relevant
record for a loan case type, so that it is easily available in App Studio when you build your loan application
form.
You can mark only certain rule types as relevant records. For more information, see Relevant records for
rule reuse.

You can mark records that are outside classes that Pega Platform provides by default, such as @baseclass or
Work- classes.

Pega Platform automatically marks any records that you create in App Studio, such as properties, as
records relevant to an appropriate context.

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

2. Open the rule form of a record that you want to mark as relevant:
To open a property, click Data Model Property .
To open a data transform, click Data Model Data Transform .
To open a strategy, click Decision Strategy .
To open a decision table, click Decision Decision Table .
To open a when rule, click Decision When .
To open a correspondence rule, click Process Correspondence .
To open a flow, click Process Flow .
To open a flow action, click Process Flow Action .
To open a notification rule, click Process Notification .
To open a Pulse feed rule, click Process Pulse Feed .
To open a validate rule, click Process Validate .
To open a SLA, click Process Service Level Agreement .
To open a harness, click User Interface Harness .
To open a paragraph, click User Interface Paragraph .
To open a section, click User Interface Section .
3. In the list of instances, open the rule that you want to mark as a relevant record.
4. On the header of the rule form, click Actions Mark as relevant record .
5. Click Submit. Result: Your application marks the record as relevant for the applies to class of the record.
The record is now available for reuse and configuration in your application.
6. Optional: To verify that the record is now relevant for the class, on the confirmation message, click
View, and then review the relevant records landing page.
 App Studio overview
Installing components
Creating a rule
Configuring a data model for a case
Views for cases

Adding a relevant record to a specified class in your application

Adding a relevant record to a class

Expand the library of relevant records by adding records and classes that are most likely to be reused for a
case or data type.

For efficient management of resources, promote a rule from a built-on application so that you can reuse the
rule in another class. By supplementing your inherited rules with relevant rules of your choice, you can
create data types and case types in a quicker and more efficient way.
Before you begin: For Pega Platform version 8.5 and earlier, ensure that you meet one of the following
conditions to successfully add relevant records to a specific class:

Ensure that the classes to which you add relevant records are in rulesets that do not start with Pega-
unless you have developer access.
The class to which you want to add relevant records is one of the following: PegaSample-Data-Product,
PegaSample-Data-ContactInformation, Work-Channel-Triage-Email, Data-Portal , Data-.

1. In the header of Dev Studio, click Configure Application Inventory Relevant Records .
2. On the Relevant Records tab, in the Class Name field, enter the class of a case type or data type in
which you plan to use the rule.
3. Click Add Record.
4. In the Add Records dialog box, select the type and name of the rule to reuse.
Note: For data-type classes, you can select only properties.
5. Click Submit. Result:

Relevant records added for a selected class

 The relevant rule is ready for reuse in the list of relevant records that is available in the application.

Marking relevant records as active or inactive

Make a record available or unavailable in App Studio by marking the record as active or inactive. By
marking certain records as inactive you can narrow down the list of relevant records to suit the current
implementation context best, without the need to delete any records from your application.

1. In the header of Dev Studio, click Configure Application Inventory Relevant Records .
2. On the Relevant Records tab, select the record of interest.
3. Click the Actions menu, and then define the availability of the record:
To make a record unavailable, select Mark as inactive.

The Relevant Records tab with the Mark as inactive option

 To make a record available again, select Mark as active.
4. Click Submit.

Security of relevant records

You can define a list of relevant records in one or more case types or data types in your application before
you deliver the application to customers or other development teams. By updating a related when rule, you
can enable or disable certain access groups to add or remove relevant record entries from a class.

You can secure relevant records by updating the pyEditRelevantRecords when rule, which is part of the
.pzEditRelevantRecords internal when rule. The .pzEditRelevantRecords when rule, which contains default
conditions to secure relevant records, consists of the following when rules:

.pxEditRelevantRecords (non-editable)
This rule restricts changes to relevant records entries associated with classes in Pega- rulesets. You
cannot change the relevant records that are delivered with Pega classes, such as the Work- class.
.pyEditRelevantRecords (editable)
This rule is an extension point that you can override in your applications to define custom logic in
order to secure the relevant records that you deliver with your applications. For example, you can
save this rule to your application ruleset and modify the access group condition. For more information
about modifying rules, see Copying a rule or data instance.

Learning about access groups

Installing components
Install a component to make a reusable feature available to applications on your system.

1. Open your Application form.

2. Click Manage components.
3. Select Install new and select the zip file that includes the component.
4. Optional: Browse for components on the Pega Exchange site:
a. Click Browse Apps and Components to open the Pega Exchange site to search for other
components.
b. Browse the available components. When you find a component to add to your application, follow
the instructions on the component page to download the component zip file to your system.
c. Return to your application, and then select the component zip file.
5. Click Open.
6. Optional: Select Enabled to enable the new component for this application.
7. Click OK.

What to do next: For more information about the component, review the component documentation in
the component zip file.

Components

A component is a collection of rulesets that create a small feature that can be added to any
application created in the Pega Platform.

Enabling components

Enable components to add the component feature to your application.

Creating a component
 Create a component to support feature reuse in another system or application. You can control which
rulesets define your component and whether your component has dependencies on other rulesets or
applications.

Disabling components

Disable components to remove access to the component feature from your application.

Components

Components
A component is a collection of rulesets that create a small feature that can be added to any application
created in the Pega Platform.

Creating a component creates a new ruleset. As a best practice, do all component-related development in
this ruleset to avoid naming conflicts. After you create a component, you can package the component and
import it into another system. Then, you can enable the component in other applications on the target
system.

Access the Components landing page by clicking Configure Application Components .

Creating a component
Documenting a component
Packaging a component
Installing components
Enabling components
Disabling components

Enabling components
Enable components to add the component feature to your application.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. On the Definition tab, in the Enabled components section, click the Manage components button.
3. Select the Enabled check box for each component that you want to use in your application.
Note: The locked icon indicates that the component is ready to add to an application and is password-
protected. Unlocked components may still be in development. Use caution when you add unlocked
components to your application.
4. Click OK.
5. Click Save.

Components
Disabling components
Installing components

Creating a component
Create a component to support feature reuse in another system or application. You can control which
rulesets define your component and whether your component has dependencies on other rulesets or
applications.

1. In the header of Dev Studio, click Configure Application Components .

2. Click New component.
3. In the Label field, enter a name for your component ruleset.
4. In the Version field, enter a number that distinguishes this version of the component from previous
versions.
5. Click Create and open .
6. Update the Component rulesets. Change the default ruleset or add rulesets to the component.
7. List required Prerequisites for this component.
8. Click Save.

What to do next: Document your component so that users can decide whether to install and reuse it in
their applications.
 Documenting a component

Document the components that you create to help users decide whether they can reuse your
component in other applications.

Packaging a component

You can use a component in applications on other systems. To import a component into another
system, package the component.

Shared ruleset

A shared ruleset contains a small number of rules that each operate on a common, top-level page of a
single class (or of subclasses of that class).

Components
Documenting a component
Packaging a component

Documenting a component
Document the components that you create to help users decide whether they can reuse your component in
other applications.

1. In the header of Dev Studio, click Configure Application Components .

2. Select the component that you want to document.
3. Click the Documentation tab.
4. Optional: Upload an icon to associate with this component.

Note: The icon file must be a .png, .jpg, or a .bmp file. The icon file size must be 3 MB or smaller. The
icon must be exactly 120 pixels high and 120 pixels wide.

a. In the Overview section, click Upload icon.

b. Click Choose File.
c. Select the icon file, and click Open.
d. Click Submit.
5. Enter a Description of the component.
6. In the Key features section, enter a key feature of the component to help users understand what it
does. Click Add new to add additional features.
7. Upload a PDF file with a maximum size of 25 MB that provides information about this component.
a. Optional: Click download template to download a documentation template. Click download
example to see a sample installation guide.
b. Click Upload.
c. Click Choose File.
d. Select the file you want to add, and click Open.
e. Click Submit.
8. Click Save.

Components
Packaging a component
Creating a component

Packaging a component
You can use a component in applications on other systems. To import a component into another system,
package the component.

To package a component, follow these steps:

1. Click Configure Application Components .

2. Select the component you want to package.
3. On the Definition tab, select Locked.
4. Enter and confirm the password. You will need this password to unlock the component.
5. Click Submit.
6. Click Package Component. The system creates a zip file.
 7. Click Download to download the zip file.
8. Save the component .zip file. Do not change the default name of the file.

Shared ruleset
A shared ruleset contains a small number of rules that each operate on a common, top-level page of a
single class (or of subclasses of that class).

Shared rulesets have the following restrictions:

A shared ruleset cannot contain a class rule.

Rules must apply to classes that extend existing classes such as the Work- base class and the Data-
base class.

Typically, shared rulesets contain only a few rules. The intent is to provide a small group of rules that
provide common functions that can be shared among (unrelated) applications.

To facilitate reuse of the ruleset in multiple situations, use the keyword Top in property references in the
rules of a shared ruleset to refer to the top-level class on which the rules operate. Do not identify this class
explicitly.

When you log in, a ruleset list is developed from the information in your access group and rules that it
references. Shared ruleset versions appear near the bottom of the list, just above the standard Pega-
rulesets.

To mark a ruleset as a shared ruleset , set the RuleSet Type on the Category tab of the ruleset form to
Shared.

To include a component ruleset in your own ruleset list, identify the ruleset in the Enabled components
array on the Definition tab of an application rule referenced by your access group.

Disabling components
Disable components to remove access to the component feature from your application.

1. In Dev Studio, open the application in which you plan to use components.

2. Click Manage components.

3. Clear Enabled for each component you want to remove from your application.

4. Click OK.

5. Click Save.

Components

Creating an activity
Automate a system task for which a more appropriate rule type is not available by creating an activity.
With activities, you define a sequential set of instructions, or steps, that the activity completes
automatically. Each step calls a method or supported rule type to perform the required processing.

Consider a scenario in which an insurance company must submit insurance claims to the Registry of Motor
Vehicles. To minimize the impact on users, you can configure an activity to automate claim uploads so that
your application submits insurance claims outside of peak hours, without user intervention.
Before you begin: As a best practice, before creating an activity, investigate model-driven alternatives
that can deliver the desired results. Alternatives such as data transforms, collections, declarative rules, and
features of flows and case management can remove the need to create new activities. If possible, use the
standard activities that Pega Platform includes. To view a list of all standard activities, flows, and flow
actions that you can use in case management, in the header of Dev Studio, click Configure Case
Management Processes APIs . Create a custom activity only if the standard activities cannot fulfill your
business needs.

1. In the header of Dev Studio, click Create Technical Activity .

 2. In the Activity Record Configuration section, in the Label field, enter a name that describes the
purpose of the activity and helps identify the activity.
Start activity names with a verb that indicates the purpose of the activity. Follow the verb with a noun
or noun phrase that indicates an element on which the activity operates. Capitalize the first letter of
each word in the name of the activity.
For example: Name your activity CreateClassPage or GetHTMLFilePath to clearly convey the purpose.
3. Optional: To change the identifier that other rules use to reference this activity, in the Identifier
section, click Edit, and then enter a name that is unique within the Apply to class.
Choose a name that starts with a letter and contains only letters, numbers, and hyphens. The name
must be a valid Java identifier. The length of the class name plus the length of the identifier cannot
exceed 128 characters.
4. Optional: To automatically set the activity type and, in some cases, add prepopulated steps to the
form, click View additional configuration options, and then select one of the available activity
templates:
To create a route activity that you can use in an assignment shape to route an assignment to a
worklist or work queue by using custom routing criteria, select Template for Route type
activity for worklist. For more information, see Assignment shapes in processes.
To create a trigger activity that you can use in a Declare Trigger rule to set the values of
parameters, select Template for Trigger type activity . For more information, see Creating
Declare Trigger rules.
To create a utility activity that you can use to automate the processing of a case, select
Template for Utility type activity. For more information, see Calling an activity or an
automation from a flow.
5. In the Context section, define the context in which to execute the rule:
a. In the list of built-on applications, select an application layer for the activity.
b. In the Apply to field, enter a class that you want to associate with the activity.
At run time, the activity runs in the context of a page. The class that you specify in the Apply to
field must be either the class of that page or in the class hierarchy of that page's class. For more
information, see Understanding class hierarchy and inheritance.

The list of available class names depends on the application context that you select.

c. In the Add to ruleset list, select a ruleset and a ruleset version in which you want to store the
activity.
6. Optional: To override the default work item that your application associates with this development
change, press the Down arrow key in the Work item to associate field, and then select a work item.
For more information about your default work item, see Setting your current work item.
7. Click Create and open .

What to do next: Define a sequential set of instructions, or steps, that the activity completes
automatically. For more information, see Configuring steps in an activity.

Configuring steps in an activity

After you create an activity, define a sequential set of instructions, or steps, that the activity
completes automatically. Each step calls a method or supported rule type to perform the required
processing.

Activity form - Completing the Steps tab - Entering Method parameters

The Method Parameters section allows you to pass information from an activity to a method or
instruction specified in the Method field of a step.

Activity form - Completing the Steps tab - Entering preconditions

Use the When button to define a when precondition that conditionally skips execution of a step. The
system evaluates whether specified conditions are met before it executes the method or instruction
referenced in the step. If false, the rest of the step is skipped.

Defining step transitions in an activity

Use the blue Jump button to open a pop-up dialog, and identify transitions, optional fields that can end
iteration, terminate the activity, or cause control to jump to a later (higher-numbered) labeled step.
Use transitions to specify conditions that are evaluated after the method in the step is performed, but
before the execution continues with other steps.
 Repeating steps in an activity

Use the Loop button to identify iterations, optional fields that can define an enumeration of or loop
condition for this step.

Calling an automation from an activity

Call an automation from an activity without using a Java step.

Best practices for writing activities for background jobs

Ensure that work items are processed correctly and that data is not corrupted during a node shutdown
by using best practices for writing activities for background jobs.

Security tab on the Activity form

Use the Security tab to specify the activity type and optionally to restrict which users (or other
requestors) can execute the activity. This optional security supplants restrictions based on RuleSet
and version.

Defining the local variables for an activity

Use the Local Variables section to create scalar variables.

Activity form - how to create activities for flows

Use these instructions to create activities that can be called directly in flows.

Unit testing an activity

Creating a rule
Branches and branch rulesets

Configuring steps in an activity

After you create an activity, define a sequential set of instructions, or "steps," that the activity completes
automatically. Each step calls a method or supported rule type to perform the required processing.

Consider a scenario in which a customer service department wants to make available the content of their
support requests through a REST service. To fulfill this requirement, you can configure an activity to
validate the service parameters, gather the appropriate data, and construct a JSON response.
Before you begin:

Create an activity. For more information, see Creating an activity. Determine whether and how other
rules can reference this activity by selecting an appropriate activity type on the Security tab. For
more information, see Security tab on the Activity form.

Note: Limit each activity to 25 or fewer steps. To promote modularity and maintainability, use 15 or fewer
steps and set the activity to complete one task.

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

2. Expand the Technical category and click Activity.
3. Open the activity that you want to configure.
4. Optional: To temporarily exclude a step from running by commenting that step out, on the Steps
tab, in the Label field, enter //.
Note: An excluded loop step excludes all child steps from running.
5. Optional: To allow other steps to reference this step in their When or Jump criteria, on the Steps tab,
in the Label field, enter a short string. For example: For a step that sets an error code, enter error.
6. Optional: To repeat a step or a contiguous sequence of steps a number of times, click Loop, and
then define a loop.
The most common way to loop is to iterate over a Page List property, such as pxResults, by using the
For each embedded page option. For more information, see Repeating steps in an activity.
For example: Delete each embedded page by using the Page-Remove method.
7. Optional: To complete a step only if specific parameters fulfill conditions that you define, click When,
and then define the preconditions for the step.
For more information, see Activity form - Completing the Steps tab - Entering preconditions.
8. Click the Method field, press the Down arrow key, and then select a method or instruction that you
 want to complete. For example: To retrieve a list of data instances that match a specific set of
parameters, enter Obj-Browse. To set the value of a specified property, enter Property-Set.
9. Optional: To set a context for the step that is different than the primary page of the activity, specify
the name of the page or property that you want to use as the context.
By default, an activity runs within the context that calls that activity. For example, an activity that a
Utility shape calls during case processing runs within the context of pyWorkPage , which is the page
that is assigned to the case type. Complete the following steps only if you want to change the default
context:
a. On the Pages & Classes tab, add the page or property that you want the system to use at run
time.
For more information, see Defining the pages and classes of a rule.
b. In the Step Page field, enter the name of the property that you want the step to use as context.
Depending on the scenario, you can use additional syntax. For example, if you select the For
each embedded page loop in step 6, enter a full property reference to a Page List property,
such as pagename.pxResults.
For example: To copy a specific order from a list of previous orders in memory, set the step page to
the appropriate page in the page list of results.
10. Click Expand to see method parameters.
11. In the Method Parameters section, configure how your application applies the method or instruction
that you selected in step 8:
For methods, enter parameters specific to a particular method.

For example, if you selected the Obj-Browse method, in the PageName field, enter the name of
the page on which you want to store the results, and then in the ObjClass field, enter the name
of the class that you want the method to browse.

For instructions, such as Call, Branch, Collect, or Queue, enter parameters specific to the rule
that is associated with the instruction.
If you selected Java, in the Java Source field, enter Java source code that you want the activity
to run.
For more information, see Activity form - Completing the Steps tab - Entering Method parameters
Result: At run time, the system passes the values that you specify to the method or instruction. The
system holds the parameter names for a step on a special clipboard page that is called the parameter
page, which is visible during tracing, but not with the Clipboard tool.
12. Optional: To specify conditions to evaluate after the method in a step runs but before the activity
moves to the next step, click the Jump link, and then define a transition.
For more information, see Defining step transitions in an activity.
13. Click Save.
14. If your activity contains Java steps, ensure that the activity causes no security issues by running the
Rule Security Analyzer tool before locking a ruleset version.
For more information, see Searching for security vulnerabilities in rules.
15. Optional: To configure another step in the activity, click Add a step, and then repeat steps 4
through 14.

What to do next:

Define input parameters for the activity. For more information, see Defining the input parameters of a
rule.

Tip: When you define the input parameters, select In or Out to indicate whether the parameter is used
for input to the called activity, or output from the activity. Using input parameters can make activities
easier to understand, call, and test.Caution: The system does not prevent you from setting the value
of an input parameter. A called activity can access and change both input and output parameters on
the parameter page.

Create scalar variables that you can use to pass information between the steps of an activity. For
more information, see Defining the local variables for an activity.

Creating an activity
Unit testing an activity
Creating a rule
Branches and branch rulesets

Activity form - Completing the Steps tab - Entering Method

parameters
The Method Parameters section allows you to pass information from an activity to a method or instruction
specified in the Method field of a step.

Completing the Method Parameters section in a step

1. Enter a method name or instruction in the Method field.
2. Click the Expand icon to expand the step.
3. Review the fields in the Method Parameters section. These fields dynamically update based on the
value you specified in the Method field:
For method names, parameters specific to the method appear.
For instructions, parameters specific to the rule name associated with the instruction appear. The
keywords Call, Branch, Collect, Queue, Flow-New, or Rule, followed by a rule name are examples of
instructions.
For a Java instruction, a text area appears where you can enter inline, Java source code.
The message "No parameters" appears when the specified method or instruction does not accept
any parameters.
4. Note: Enter values in each field, using the SmartPrompt to help you select an option from a list where
available. Icons appear next to a field when appropriate:
Star – Indicates the field is required.
Magnifying glass – Opens the rule referenced in the field.
Build an expression – Launches the Expression Builder.

At run time, the system passes the values specified in the Method Parameters section to the method or
instruction. If applicable, a parameter page is created for the step that is separate from the parameter
page of the activity. This separate parameter page is destroyed when the step completes.

In some cases, you can use the parameter page of the activity to pass information instead of explicitly
setting values in the Method Parameters section. This technique is referred to as passing parameters by
reference.

Passing parameters by reference

1. Ensure that the parameter values required by the method or instruction are present on the parameter
page of the activity before the step executes.

This is typically done by a previous Property-Set step in the activity or a rule higher up in the call stack.

2. Enter a method name or instruction in the Method field.

3. Click the Expand icon to expand the step.
4. Select the Pass current parameter page check box.

At run time, the parameter page of the current activity is passed to the method or instruction. This page
returns to the activity when the step completes.

Passing parameters by reference allows the called method or instruction to modify the parameter page.

Creating an activity

Activity form - Completing the Steps tab - Entering

preconditions
Use the When button to define a when precondition that conditionally skips execution of a step. The
system evaluates whether specified conditions are met before it executes the method or instruction
referenced in the step. If false, the rest of the step is skipped.

Click the button to access the details of the precondition.

Use the add row and delete row icons to define the condition. Order is significant. You can rearrange the
order by selecting the row number and dragging it up or down. Click OK to save your edits and close the
dialog.
 Field Description

Enable
conditions
Select to turn on the precondition test. If this box is not selected, all the rows are hidden and
before
are ignored at runtime. The gray When button appears.
this
action

Identify a when condition rule that specifies this precondition. Or enter an expression starting
with "=" that returns true or false, such as
=(.pyDoorisLocked == false).

When Click the Open icon to review or update the when condition rule. Click to start the
Expression Builder.

within the precondition and transition elements of a step that

You can use the keyword <CURRENT>
also includes a repeat element to evaluate the current element of the repeat.

Select to indicate what is to happen if the when condition evaluates to True. Complete both
an If True and an If False option for each precondition row.

Continue Whens — Advance to the next row of the precondition array, before executing
the step.
If True Skip Whens — Skip all the later rows and execute the step.
Jump To — Jump to a specific higher-numbered activity step that contains a label.
Entering the step's Label name in the True Param field. Processing resumes at the
labeled step. You cannot jump to a label for a lower-numbered step.
Skip step — Skip the current step. For a repeating step, this ends the iteration.
Exit This Iteration — End the current iteration, and advance to the next iteration.
End Activity — End execution of this activity. The rest of the step is not executed.

True Param If you selected Jump To , enter the Label name of the step to jump to.

If you entered Exit Activity, enter an integer: 0 for a status of Good, any negative integer for a status of Fail,
and any positive integer for a status of Warn.

If False Choose what is to happen if the condition evaluates to false. The choices are the same as those for
If True. As a good practice, complete both an If True and If False option for each row. False Param If you
selected JumpTo, enter the label of the step to jump to.

Viewing test coverage reports

Creating an activity

Defining step transitions in an activity

Use the blue Jump button to open a pop-up dialog, and identify transitions, optional fields that can end
iteration, terminate the activity, or cause control to jump to a later (higher-numbered) labeled step. Use
transitions to specify conditions that are evaluated after the method in the step is performed, but before
the execution continues with other steps.

Often a transition condition tests whether the method in the current step was successful. See How to test
method results using a transition for more on this use of transitions.

Use the add row and delete row icons to define the condition. Order is significant. You can rearrange the
order by selecting the row number and dragging it up or down. Click OK to save your edits and close the
dialog.

Field Description

Enable
 conditions
Field Select to activate the transition. If thisDescription
box is not selected, all rows of the transition are
after this hidden and are ignored at run time. The gray Jump button is available.
action

On
Optional. If you anticipate that this method might cause a Java exception, enter the label of a
exception,
higher-numbered step to execute next. This can prevent users from seeing any evidence of
Jump to a
the exception, such as the red X. This setting does not apply if an exception occurs in a
later step
precondition to the step.
label:

Identify a when condition rule that the transition is to evaluate. Alternatively, enter an
expression that returns true or false, starting with =.

Click the Open icon to review or update the when condition rule. Click to start the
When Expression Builder.

within the precondition and transition elements of a step that

You can use the keyword <CURRENT>
also includes a repeat element to evaluate the current element of the repeat.

Select which action the system is to take when the when condition or conditions evaluate to
true. Complete both an If True and If False option for each row.

Continue Whens — Advance to the next row of the transition.

Skip Whens — Skip all the other, later rows of the transition.
Jump to Later Step — Jump to a higher numbered step that contains the specified label.
Indicate which step to jump to by entering the step's Label name in the True Param
If True field. After the activity jumps to the specified step, it processes that step and later
steps in the activity. You cannot use Jump to Later Step to transfer control to a label of a
lower-numbered step.
Skip Step — End processing of this step, continuing at the next step. If the current step
involves an iteration, this choice operates similarly to a break statement in many
programming languages.
End Activity — End execution of this activity. This is similar to the Exit-Activity method,
not the Activity-End method.

True Param If you selected Jump to Later Step for the If True field, enter the label of a higher-numbered step to
jump to.

If the If True value is Jump to Later Step and the transition is true, but this field is empty, a Java exception
occurs.

If False Select what action the system is to take if the condition evaluates to false. The choices are the
same as those for If True . Complete both an If True and If False option for each row. False Param If you
selected Jump to Later Step for the If False field, enter the label of a higher-numbered step to jump to.

If the If False value is Jump to Later Step and the transition is false, but this field is empty, a Java exception
occurs.

Note:

You cannot use an iteration to jump from outside an iteration sequence to any child step within the
iteration. You can jump to the parent step — first step (NNN.0) of an iteration sequence. From a child step
in an iteration, you can jump to a later step within the iteration or to a later step outside that iteration.

When a method in an activity step affects the value of a property referenced in a Declare Expression rule,
the declarative rule execution occurs before the system evaluates the transition. For example, if the
method updates the value of a Diameter property, and a Declare Expression rule computes a CircleArea
property based upon the Diameter value, only the updated CircleArea value is available to the transition.

When a step contains an enabled when-based transition, the Tracer shows a step status of "Good"
regardless of the step status that existed before the transition evaluation. This status is consistent with the
processing status that will be perceived by the next activity step; it reflects that any error condition that
existed is "noted" by the activity.

Viewing test coverage reports

Creating an activity

Repeating steps in an activity

Use the Loop button to identify iterations, optional fields that can define an enumeration of or loop
condition for this step.

Loops repeat a step or a contiguous sequence of steps a number of times, or until a condition is met. You
can iterate over the elements in an aggregate property — a Value List, Value Group, Page List, or Page Group.

This feature provides a limited form of enumeration or looping, similar to the "repeat until" or "do while" or
"repeat from X to Y" structures of programming languages.

Note: In a child step within a multistep loop, right-click to access a context menu. You can copy, cut, or
paste child steps within the same iteration.

Repeating a single step using the loop field

Click the Loop button to access the details of the iteration. Use the pop-up dialog to indicate whether and
how to repeat the step. You can cause the step to repeat a specific number of times, or until a specific
result is reached. Click OK to save your edits and close the dialog.

Use the Repeat selection box to apply the step to more than one page or object. Select:

For each top level page

For each embedded page
For each element in value list
For each element in value group
For loop

To exit the iteration before processing all elements in the iteration, complete a transition that is true after
the last desired element is processed.

When processing the For loop or iterating over a Value List or Page List property, the parameter param.pyForEachCount
holds the current iteration number. You can examine (but not alter) this value in the step. For example, to
iterate only over the first ten pages or values, you can exit the iteration when pyForEachCount is greater than
10.

Note: If the body of the iteration requires more than one step to code, create an activity and call the
activity in the iterated step. Select the Pass current parameter page? check box to share the parameter
page of the current activity with the called activity.

For each top level page

Select the For each top level page option to sequence through all pages of a specified class or classes and perform
a method or instruction for each top level page. Leave the Step Page field blank. Each time the step
repeats, the step's page changes.

For the optional Only Loop for Certain Classes parameter, enter a class or classes. (Click the Add Row icon
to add more than one class.)

When Only Loop for Certain Classes is not blank, iteration processing skips over any page with a class that
does not appear on the list, or is not derived from one of these classes.

Use the add row icon to add a class. You can rearrange the order by selecting the row number and moving
it up or down.

For each embedded page

Use For each embedded page option to apply a method or instruction to each embedded page in a Page List or Page
Group property. Use the iteration choice to specify processing that is to occur for each embedded page. For
example, you can:

Copy each embedded page

Delete each embedded page using Page-Remove
Delete a property on each embedded page
Add a property to each embedded page

and so on.

Identify the property containing the embedded pages in the Target field. The SmartPrompt list for the
Target field shows only Page List and Page Group properties.

For the optional Only Loop for Certain Classes parameter, enter a class or classes. (Click the Add Row icon o
add more than one class.)

When Valid Classes is blank, all pages of the Page List or Page Group are included in the iteration.
When Only Loop for Certain Classes is not blank, iteration processing skips over any page with a class
that does not appear on the list, or is not derived from one of these classes.

For each element in a value list

Select the For each element in value list option to repeat the step for each element in a Value List property.

Each time the step repeats, the system applies a method or instruction of your choice (such as Property-
Set) to the current property. Use the <CURRENT> index value to refer to the current property element.

When you select this iteration form, a Value List Property field appears. Identify the Value List property in the
field.

For each element in a value group

Select the For each element in value group option to repeat the step for each element in a Value Group property.

When you select this iteration form, a Value Group Property field appears. Identify the Value Group property in
the field.

Each time the step repeats, the system applies a method or instruction of your choice to the current
property. Use the <CURRENT> index value to refer to the current property.

For loop
Select the For loop option to repeat the step a number of times determined by the values of integer constants
or integer properties.

Enter integer constant values or integer property references for the Minimum Value, Maximum Value, and
Increment fields. The Increment must be a positive integer.

The system accesses these three values once before starting the iteration. The iteration may occur zero,
one, or many times, repeating until the incremented value is greater than or equal to the stop value (unless
a transition causes processing to end earlier).

Understanding <CURRENT>
The symbolic reference <CURRENT> can be used only in the activity step that defines the iteration. If that
step calls another activity, the symbolic reference <CURRENT> cannot be used in the called activity; rather,
aspects of the current iteration are available on the parameter page of the called activity:

For a repeat type of For each element in value list or For each element in value group, the symbol <CURRENT> refers to
the value of ClipboardProperty corresponding to the iteration. For the called activity, this corresponds
to the pyPropertyValue parameter described below.
For a repeat type of For each embedded list, <CURRENT> refers to the ClipboardPage of the current iteration: for
example, when used in an RUF call that takes a ClipboardPage parameter or on the right side of a
property set when the target is a page (when you add to a page list using .list(<append>) ).
For other repeat types, <CURRENT> refers to the index number of the current iteration, and corresponds
 to the pyForEachCount parameter.
<CURRENT> can be used within the precondition and transition elements of a step that also includes a
repeat element to evaluate the current element of the repeat.
Within a repeat block, <CURRENT> can appear in the Expression Builder for the Target field of a
Property-Set method; the keyword will refer to the current element’s property so that it can receive
the new value.

Multistep loops
The scope of a loop can be more than one step. The loop type and conditions are set in the first step of a
multistep loop.

To create a multistep loop:

1. Identify the step that is to be first in the loop. Click Loop to access the pop-up dialog, and complete
the loop details.
2. Complete information for the first step. Identify the step page. Optionally, you can leave the method
blank.
3. Select the stage, open the right-click context menu, and select Add Child. The current step is
renumbered as NNN.0, where NNN was the previous step number. The form changes to include a new
later step NNN.1. The scope of the iteration is now both NNN.0 and NNN.1. This zero-numbered step is
known as the parent step.
4. Complete NNN.1, a child step. Leave the Step Page field blank and the iteration criteria blank in most
cases, to have the child steps operate on the step page identified in the parent step. Optionally, you
can override this step page of a child step by entering one of the following:

a top-level page (such as the primary page).

a reference to a page relative to the step page of the parent.
a reference to a Page List or Page Group property on the step page of the parent. (In this case, complete
the For each embedded page iteration details for the child step.)

1. To create an iteration of more than two steps, click within the parent step NNN.0 again to make it
active, and select the Add Child menu option gain.

Numbered child steps are executed in sequence NNN.0, NNN.1, NNN.2 ... then NNN.0 again, until the
iteration ends or a transition causes a jump to a labeled step.

You can add addition child steps at the same level by placing the mouse pointer in the Description field and
pressing the Enter key.

To convert an iteration sequence to comments, enter two slash characters // in the Label field of the parent
step. The parent and all child steps become comments.

Note: You cannot jump from outside a multistep iteration to any step within the iteration (except to the
starting — parent — step). You can jump from any step in an iteration (parent or child) to a higher-
numbered step (that is not within any iteration).

For an example of multistep and nested iterations, see the Pega Community article How to use multistep
loops and nested loops in activities.

Nested iterations
By using the Add Child menu option on a child step numbered NNN.Z, you can create a nested iteration.

For example, clicking a child step numbered 14.8 converts this to 14.8.0, and inserts a second-level child
step numbered 14.8.1. Complete the iteration conditions for step 14.8.0.

Use care in entering the Step Page for the parent step of a nested iteration (14.8.0 in this example). If you
refer to an aggregate property (Value Group, Value List, Page Group or Page List), select a property that
reside on the <CURRENT> step page of the parent's parent. (That is, the structure of the iteration must follow
the structure of the page). Within a nested step that does not have a repeat element, <CURRENT> inherits the
semantics of its parent step that does have a repeat element.

Note: From within a nested iteration, you can jump (using a transition) to a labeled step that is within an
outer iteration but higher numbered. You can jump from 14.8.9 to 14.10 or 17, but not from 14.8.9 to 14.3.
Restrictions
If a step is part of an iteration sequence, the method cannot be any of the following:

Page-Change-Class
Connect-Java
Page-Merge-Into
Obj-Open
Page-New
Obj-Open-By-Handle
Page-Validate
Obj-Sort
RDB-Open

Parameters available to called activity

The Pega Platform automatically adds the following parameters to the parameter page of a called activity
with a step that contains an iteration.

— Index of the current iteration, normally starting at 1 and incrementing by one. (If the
pyForEachCount
iteration type is For loop, the starting value may be a value other than 1 and the increment may be a
value other than 1.) This parameter is available throughout the iteration as well as in called activities.

pyIterationType — Indicates the iteration type, internally represented by one of the constants page, embedded,
propertylist , propertygroup, or repeat. (This parameter values are not available to other methods in an iteration
step.)

— Identifies the name or reference of the iteration. For page and repeat types, it is blank.
pyIterationTarget
For embedded, it is the step page reference. For propertylist or propertygroup, it is the property specified in
the iteration. (This parameter values are not available to other methods in an iteration step.) (This
parameter values are not available to other methods in an iteration step.)

— Available only for propertylist and propertygroup iterations. The text value of the current
pyPropertyValue
property. (This parameter values are not available to other methods in an iteration step.)

pyPropertyReference — Obsolete. Set to "???" for backward compatibility.

pyPropertyType — Obsolete. Set to "???" for backward compatibility.

Viewing test coverage reports

Creating an activity

Calling an automation from an activity

Call an automation from an activity without using a Java step.

1. In the Method field of a step in an activity, select Call-Automation.

2. Click the arrow to the left of the Method field to expand the step and view the method parameters.
3. In the Resource field, select the type of automation that you want to call.
4. In the Automation field, select the automation that you want to call.
5. Complete the Map from and Map to fields for the inputs and outputs for the automation you are
using.
This establishes the relationship between the resource inputs settings, and the resource outputs
generated automation errors. You can view a description of these fields by viewing the automation
rule. For more information, see Viewing automations.

You do not have to use all of the outputs. To use an output, you must provide a property reference
that can hold that type of output, for example, a string property for a string output. Like inputs,
outputs are also validated. Errors that occur when the automation runs are returned in the Automation
Errors output. If an error occurs that is not in the automation rule, it is converted to a run-time error
before being returned.

Note: Page type outputs expect a property type string. A page reference is stored in that property so
 that you can return to that page later
6. If you specify a default value in the automation, in the Inputs section, a Use default value option is
displayed next to the corresponding Map from field. You can use the default value or specify a new
default value:
To use the default value specified in the automation, click Use default value. The value in the
Map from field becomes read-only, and the Use default value option changes to Specify
value.
To specify a new default value, in the field for which you want to change the value, press the
Down arrow key to select a value.
Note: If a list of values is specified for a text input in the automation rule, only those values are
available in the Map from field.
7. Click Save.

Call-Automation method
Automations

Best practices for writing activities for background jobs

Ensure that work items are processed correctly and that data is not corrupted during a node shutdown by
using best practices for writing activities for background jobs.

Queue processors, job schedulers, and agents are background jobs that use an activity to implement
processing logic. These activities are expected to finish processing in less than a few seconds. If an activity
takes longer to complete, use the following best practices to ensure that work items are not affected during
the shutdown process.

Create small work items

If possible, break down large work items into smaller work items, queue them to a queue processor, and
process them individually. Use a queue processor instead of an agent because queue processors provide
better performance, resiliency, fault tolerance, and flexibility than agents. Scale queue processors
horizontally by increasing the number of nodes configured with the node type. Scale queue processors
vertically by increasing the number of threads. For more information, see Managing queue processors in
Admin Studio help.

Use checkpoints
To ensure that activity logic can gracefully handle restarts without corrupting data or introducing
inconsistencies into your application, use checkpointing by saving the state of jobs in persistent storage or
as messages in a queue that is appropriate to the use case.

For example, consider a scenario where a work object can have the following statuses: NEW, IN-PROGRESS,
and PROCESSED. You can read all of the work object records to be processed, loop through them one by
one, mark the status of the current work object as IN-PROGRESS, continue with the business logic, and
when processing is finished, change the status to PROCESSED.

Divide and scale tasks

If you have background tasks that can be broken down into multiple tasks that have different performance
capabilities, consider dividing them and scaling each independently. Queue processors can be scaled
horizontally by increasing the number of relevant nodes and can be scaled vertically by increasing the
number of threads. For more information, see Managing queue processors in Admin Studio help.

Create sub-activities
Split activities into sub-activities when possible so that the state is saved frequently, ensuring that if there
is an abrupt node shutdown, the sub-activities can proceed based on the recovered state.

For more information about agents, job schedulers, and queue processors, see the Admin Studio help.

Viewing test coverage reports

Security tab on the Activity form
Use the Security tab to specify the activity type and optionally to restrict which users (or other requestors)
can execute the activity. This optional security supplants restrictions based on RuleSet and version.

You can specify zero, one, or more than one privilege to restrict access. Order is not significant. At runtime,
any match between a privilege listed and those a user possesses allows users to execute this rule.

Field Description

Restrict
Access

Select to allow users to start this activity directly through user input processing, for
example through a Submit button or a pyActivity= element in an URL. Clear this if this
activity is to be started only from another activity, through a Call, Branch, or other
means.

Allow direct For example, select the box for a service activity, or if this activity is called by an AJAX
invocation event from a form.
from the
At run time, if the box is not selected and a user attempts to start this activity by user
client or a
input, the activity does not run and returns a method status of Fail:Security.
service
For most activities, leave this box cleared to promote security of your application.
Unless needed by your design, allowing activities to be started from a URL or other
user input — whether the requestor is authenticated or a guest — may let users bypass
important checking, security, or setup.

Select to require that only authenticated requestors can start this activity.

Clear to allow guest users to run this activity, if they meet other security and access
criteria. Guest users — unauthenticated requestors — typically have access to rules in
the RuleSets provided in the PRPC:Unauthenticated access group, as referenced in the
Requestor type instance named pega.BROWSER.

Caution: If you update the BROWSER requestor type to reference a different access
group, or update the PegaRULES:Unauthenticated access group to make additional
RuleSets available to unauthenticated users, review carefully this check box for each
Require activity in the RuleSets. Select this check box for all but those specific activities that
authentication guests need to run.
to run
In most cases, clear this check box if the activity is for an agent. Agents are not true
authenticated users and by default cannot run activities that are restricted to
authenticated users. However, this check box is ignored by agents for which the
Bypass activity authentication check box (on the Security tab is checked; they can run
activities regardless of the Authenticate? value.

Identify privileges in this array to restrict which users and other requestors can execute
this activity. At runtime, if the user does not possess an access role that — through an
Access of Role to Object rule — provides access to one of the identified privileges, the
execution of the activity fails.

Privilege Optional. Identify the Applies To key part of a class to use at runtime to locate a
Class privilege rule. Normally this is the same as the Applies To key part of this activity.

Optional. Identify the name for a privilege in that class (or an ancestor class). The class
Privilege
you enter and the name must together identify a privilege (using rule resolution
Name
including class inheritance.)

Usage

Determine whether and how this activity can be referenced in other rules. For an
activity that is not to be referenced in a flow, choose one of these values:
 Field Select whenDescription
no more specific value is applicable. Activities
Activity with this value cannot be referenced directly in flows.
(Select Activity for this field on Parse Structured forms.)

Select for an activity that runs in a background thread

asynchronously. The activity can call only these step
Asynchronous methods: Load-DataPage, Connect-Wait, and Call-Async-
Activity (step instruction to allow user to load an
asynchronous activity)

Select for an activity that adds values to data pages.

LoadDeclarativePage Reference this activity on the Definition tab of a data page
rule ( Rule-Declare-Pages rule type).

The Locate activity type is not supported. Existing activities

Activity Type
Locate that use locatable pages display this option. New activities
do not.

Select for an activity to be executed automatically by a

Declare OnChange rule, Such activities must not use any
methods that directly change the properties or the
database.
OnChange
Declare Expression rules do not evaluate during the
execution of an OnChange.activity. OnChange activities
must not perform any forward chaining themselves.

Select for an activity to be executed automatically by a

Declare Trigger rule. Because triggered activities run
Trigger
during database commits, they cannot themselves commit
database transactions.

Select Notify, Rule Connect, Assign, Route, or Utility if the class of the activity inherits from the Work- base class and
you designed and implemented the activity to be referenced in a flow shape. See How to create activities
for use in flows for more details on these choices:

Choose Notify for a notification activity. For example, a notify activity can send an email message to
someone conveying news of the assignment.

Choose Assign for an assignment activity, one that creates an assignment.

Choose Route for a router activity, one that determines which user worklist or work queue is to receive an
assignment.

Choose Utility for a utility activity, one that automates processing without user interaction.

Choose Rule Connect for an activity that operates without user interaction and calls a connector rule to
interface with an external system.

Do not choose Validate or Assembler for this field.

Viewing test coverage reports

About Declare OnChange rules
Declare Trigger rules
Activity form - how to create activities for flows

Defining the local variables for an activity

Use the Local Variables section to create scalar variables.

Local variables are stored together as fields in the Java class that the Pega Platform generates to
implement the activity. These require less memory and execute faster than regular parameters. They are
often used to pass information from step to step.
Local variables do not appear on the parameter page.

A local variable of type StringBuffer may be assembled in multiple steps, as a Property-Set on a

StringBuffer appends the value to the StringBuffer.

Use the Local keyword to reference a local variable in a Property-Set method.

Note: To avoid Java null pointer exceptions, the system initializes String local variables to the empty string,
and the StringBuffer local variable as:
public StringBuffer aBuffer = new StringBuffer();

Caution: Accordingly, do not list a local variable as the destination for an Out parameter. Do not pass a
parameter reference as the destination for an Out parameter, unless passing the entire parameter page.
Field Description

Local Variables

Enter the name you choose for the local variable, any legal Java identifier. See How to
Name enter a Java identifier. Don't choose a name that starts with pz or any of the reserved
names.

Description Enter a text description of this local variable, for information only.

Select the type of data that is expected as the value for the variable. Choose:

String for a Java.lang.string object

String Buffer for a Java StringBuffer object
int for a Java int
Data Type double for a Java double
boolean for a Java boolean
char for Java char
BigDecimal for the BigDecimal class
Object for any Java object

Local Action for

Parameter
Display

Optional. Specify a flow action to use at runtime to produce a prompt form in which a
Local Action
user can enter values for the flow parameters specified in this tab.

Activity form - how to create activities for flows

Use these instructions to create activities that can be called directly in flows.

Flow processing automatically controls locking and transaction boundaries for work items. Do not use the
Commit method (or the Obj-Save method with the WriteNow parameter selected) in any custom activity
called by a flow.

Activity Type
The value of the Activity Type field on the Security tab determines which flow shapes accept this
activity. To create an activity for a flow, set the Activity Type field to Utility, Rule Connect, Assign, Notify, or Router
as appropriate.

First, explore the standard activities of the type you need, as examples and as starting points for your
activity.

In all but rare situations, choose a class derived from the Work- base class for the Applies To key part of
your activity. This makes your activity available to flows in that class plus all subclasses of the class
(subject to security restrictions, rule resolution restrictions and so on).

Guidelines for Utility activities

 Follow these guidelines to create a Utility activity, one that can be referenced in a utility shape:

Select Utility as the Activity Type.

In the activity, do not use the Show-HTML method or interact with a user.
Utility The activity can save a new or updated object with the Obj-Save method.
Optionally, this activity can use the TaskStatus-Set method to return a text value in the
pxTaskStatus property to the flow as a basis for decisions. Connectors leading from the
activity can be based on this status value. Using this method can simplify flow diagrams by
eliminating fork or decision shapes that follow a utility shape.

Guidelines for Assign activities

Follow these guidelines and constraints to create an activity of type Assign, one that you can
reference in an assignment shape:

Assign In the activity, do not use the Show-HTML method or other means to interact with human
users.
Create and save an instance of a concrete class derived from the Assign- base class.
Typically, a new assignment is an instance of the Assign-Workbasket or Assign-Worklist
standard class.

Guidelines for Integrator activities

Use an Activity Type value of Rule Connect to make the activity available to an Integrator
shape. Generally, use this for activities in a Work- class that call a rule to start a connector
interface to an external system.
Integrator This activity type (and the corresponding Integrator shape) is a reminder that this shape
depends on an external system. Response time, availability, and performance may be
affected by outside factors.

Like the Utility activity type, a Connect activity type cannot include HTML displays.

Guidelines for Notify activities

Select an Activity Type of Notify to identify activities in a Work- class that generate
correspondence.

A Notify activity is an activity of the notify activity type on the Security tab. The Notify activity,
when referenced in a flow, sends out correspondence, such as an email message, when a running
Notify flow creates an assignment. Typically, the application sends this correspondence to one or more
of the work parties identified in the work item, and then reports progress to that party.

The notify activity you select can accept input parameters. Provide a value for each parameter.
The system validates these parameter values when you save the flow.

Guidelines for Route activities

Follow these guidelines to create an activity with Activity Type of Route, one that can be
referenced in a router shape:

The results of the activity are a work queue name, an Operator ID (for the worklist) or an
agent name.
The activity does not display HTML forms or interact with a user.
The activity returns its results in an output parameter named AssignTo. This parameter is an
 output only, and does not need to be declared on the Parameters tab.

Many routing activities accept these Boolean input parameters:

Parameter Description

If this parameter is true, the activity is to check Operator ID instances for

CheckForAvailability availability, and follow the rules to obtain a substitute if the operator is not
available. (Standard routing activities support this parameter.)

Allows an assignment to be routed to either a work queue or worklist. Use

this Boolean output parameter in a router activity that is referenced in
assignment shapes where the Rule field on the Assignment Parameters
panel is set to Worklist.
Route SwitchToWorkbasket
When SwitchToWorkbasket is set to false, the AssignTo parameter identifies an
Operator ID for a worklist; when set to true, the AssignTo parameter is to
identify a work queue name.

Allows creation of an assignment instance to be bypassed, with the flow

execution continuing with a default flow action — the most likely flow action
— that requires no user input.
PassthroughAssignment
Set this Boolean output parameter to false in the normal case, or true to skip
the assignment and continue flow execution as if the user chose the
highest-likelihood flow action.

Influences the Properties panel to allow the entry of one or more skill
names (literal values or property references) and skill levels (integers).

A check box for each skill can mark the skill as required to perform an
UsesSkills assignment, or (if not selected) desirable to perform the assignment. The
activity can call standard functions to test whether a specific operator
possesses the required skills, or possesses the desired skills, at the indicated
level of proficiency.

The standard Routing library (in the Pega-ProCom RuleSet) contains several functions useful in router
activities.

Available parameters
When a flow calls an Integrator, Utility, Notify, or Assign activity, or another flow, it provides twelve parameters to
the activity beyond those declared in the Parameters tab. Click the Show System Parameters button
on the Parameters tab to review the names and purpose of the six parameters most often used.

Parameter Description

flowName The subscript of this flow in the work page pxFlow property, a Page Group.

The shape name of the shape that this activity or flow was called from, such as
TaskName
SendResolutionEmail or SplitForEach999.

pyDraftMode True if the flow is in draft mode.

ReferenceInsKey pzInsKey of the work item page.

ReferenceClass Class of the work item page (the work type ).

ReferenceInsName pxInsName of the work item page.

ReferencePageName Clipboard page name of the work item page.

TimeFlowStarted Date and time that the flow execution began.

 Property reference to the embedded page of the work item that is the primary page of
Parameter Description
the flow. (This is null if the flow's primary page contains the work item.)
InterestPage For example, a flow executing on the Customer work party has an interest page of
.pyWorkParty(Customer).

Class of the interest page, for example Data-Party. This is an empty string if the flow's
InterestPageClass
primary page is the work item itself.

A Boolean used by internal flow processing to control whether one flow calling another
FlowHasEnded
is to wait or to continue.

flowType Second key part of the flow.

Intelligent routing

Intelligent routing is the process of comparing the characteristics of a new assignment with the
characteristics of the workforce to route the assignment to the most appropriate operator. Like a
supervisor who thoughtfully distributes work to her team, intelligent routing in your application can
significantly affect the productivity and throughput of a team.

Viewing test coverage reports

Intelligent routing
Intelligent routing is the process of comparing the characteristics of a new assignment with the
characteristics of the workforce to route the assignment to the most appropriate operator. Like a supervisor
who thoughtfully distributes work to her team, intelligent routing in your application can significantly affect
the productivity and throughput of a team.

An intelligent routing algorithm can examine many factors, such as backlogs, the presence or absence of
operators, operator skills, the urgency or priority of an assignment, and a customer's location or time zone.
Your system includes the following three standard activities as examples:

Work-.ToSkilledGroup — Implements skill-based routing. This activity sends an assignment to a

randomly selected operator within a specific team. This operator is available between the time the
assignment starts and is due, and has the minimum skill proficiencies to complete the assignment.
Using indexes maintained in the Index-OperatorSkills class, this activity operates efficiently.
Work-.ToLeveledGroup — Sends an assignment to an operator within a specific team who has the least
urgent total worklist, based on a computed score.
Work-.SampleToSkilledGroupList — Demonstrates use of the getAvailableSkilledOperatorsList()
function. Part of the Routing library, returns a list of operators who are available and meet the required
skill requirements. Your routing algorithm can apply additional filtering and criteria to select which of
the operators on the list receives the assignment. (If none of the operators in the group meet the
standard function qualifications, the list contains only the team manager's Operator ID.)

Skill-based routing is an important type of intelligent routing. Skill-based routing compares the skill
proficiency of operators in a team with the required and desired skills to perform an assignment accurately
and quickly. For example, an assignment might require an operator who passed the NASD Series 7 exam,
and might prefer that the operator have a speaking proficiency in Spanish.

Skill-based routing affects only which work queue or which operator worklist receives an assignment. Skill-
based routing does not prevent an operator who does not meet the skill profile used in routing from
accessing an assignment in a work queue and performing the assignment.

Creating binary file rules

Enhance and customize your application by creating a binary file rule that stores a graphics file, such as an
image, or other non-text file. The binary file rule type provides the security, inheritance versioning, and
deployment benefits of rule resolution to a file.

For example, you can upload a custom image to your Pega Platform environment and use the image in your
application. You can upload different resources, such as icons, fonts, and locales.
 1. In the header of Dev Studio, click Create Technical Binary File .
2. On the rule form, in the Label field, enter a name for your rule.
3. In the App Name (Directory) field, enter the name of the destination web server directory for this file
when the system extracts the file from the database. For example: To use a subdirectory on the
application server, enter webwb.
4. In the File Type (extension) field, enter the file extension. For example: To upload a graphics file,
enter jpg.
5. Optional: To change the application layer in which to store the binary file rule, in the Context field,
select another built-on application.
By default, the system stores the rule in your current application layer.
6. In the Add to ruleset list, select a ruleset and a ruleset version in which to store the rule.
7. Optional: To override the default work item that your application associates with this development
change, in the Work item to associate field, press the Down arrow key, and then select a work item.
For more information about your default work item, see Setting your current work item.
8. Click Create and open .

Adding images to Image Library

Customize the look-and-feel of your application by including your own images in elements such as
logos, displaying an image for a button or link control, using custom sprites in the UI design, and
determining the content that users see when the system displays a guardrail warning. As a result, you
provide a unique and personalized application that can precisely reflect your business requirements.

About Binary File rules

Create a binary file rule to include a graphics file, such as an image (including GIF, JPG, or PNG files) or
other non-text files in your application as a rule. This rule type provides the security, inheritance
versioning, and deployment benefits of rule resolution to a file.

About Binary File rules

More about report definition rules

Adding images to Image Library

Customize the look-and-feel of your application by including your own images in elements such as logos,
displaying an image for a button or link control, using custom sprites in the UI design, and determining the
content that users see when the system displays a guardrail warning. As a result, you provide a unique and
personalized application that can precisely reflect your business requirements.

To use custom icons or images in your Pega Platform application,add your binary file to the Image Library.
Before you begin: Create a binary file rule of a file extension that matches a graphics file that you want
to upload, for example, .jpg. For more information, see Creating binary file rules.

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

2. Expand the Technical category and click Binary File.
3. In the list of binary files instances, click the rule that you want to edit.
4. On the File tab, in the File controls section, click Upload file.
5. In the Upload file dialog box, click Choose file.
6. In the dialog box, navigate to the file that you want to upload, select the file, and then click Open.
7. Click Upload file.
8. Optional: To use the uploaded image as an icon, define the icon settings:
a. in the Image details section, select the Treat image as a sprite check box.
b. In the Icon width and Icon height fields, enter the icon size in pixels.
9. Click Save. Result: After a successful save, you can preview the image in the Image details section.

What to do next: Incorporate the image into your UI. For more information, see Configuring actionable
icon controls.

Uploading custom font files

About Binary File rules

Create a binary file rule to include a graphics file, such as an image (including GIF, JPG, or PNG files) or
other non-text files in your application as a rule. This rule type provides the security, inheritance
versioning, and deployment benefits of rule resolution to a file.

The following tabs are available on this form:

Main

Binary file rules can also hold non-image text files, including Windows libraries (DLL file type), Adobe Flash
files (SWF file type), or Adobe PDF documents (PDF file type).

Where referenced
Any rules that contain HTML, such as harness, section, and correspondence rules, can reference binary file
rules.

Access
Use the Records Explorer to list all binary file rules available to you. Use the Image Library gadget (using
Configure User Interface Gallery Images ) to view and search the binary file rules of image file types
such as GIF, JPG, and PNG.

Category
Binary file rules are instances of the Rule-File-Binary class. They are part of the Technical category.

When searching for binary file rules, the system filters candidate rules based on a requestor's RuleSet list of
RuleSets and versions.

Time-qualified and circumstance-qualified rule resolution features are not available for binary file rules. The
class hierarchy is not relevant to rule resolution of binary file rules.

User experience

Building logic and calculating values in your application

Provide automations for calculating values and implementing logic so that your application can flexibly
respond to unique conditions at run time. For example, you can create a process of transforming data, and,
as a result, present users with relevant information when they perform work.

Data transforms

A data transform defines how to convert data that is in one format and class (the source) into data of
another format and class (the target). The supported formats are clipboard and JSON. Using a data
transform instead of an activity to set property values speeds up development and makes application
maintenance easier.

Decision tables

Decision tables derive a value that has one of a few possible outcomes, where each outcome can
result from a test of a condition that includes multiple variables. A decision table lists two or more
rows, and each row contains test conditions, optional actions, and a result.

About Decision Trees

Use a decision tree to record if .. then logic that calculates a value from a set of test conditions
organized as a tree structure on the Decision tab, with the 'base' of the tree at the left.

About Map Values

Use a map value to create a table of number, text, or date ranges that converts one or two input
values, such as latitude and longitude numbers, into a calculated result value, such as a city name.
Map value rules greatly simplify decisions based on ranges of one or two inputs. Use a map value to
record decisions based on one or two ranges of an input value. A map value uses a one- or two-
dimensional table to derive a result.
 When Condition rules

A when condition rule evaluates a Boolean logical statement involving comparisons among values of
properties, to return true or false.

About Constraints rules

Create constraints rules to define and enforce comparison relationships among property values.
Constraints rules can provide an automatic form of property validation every time the property's value
is "touched", in addition to the validation provided by the property or other means.

About Declare Expression rules

Use Declare Expression rules to define automatic computations of property values based on
expressions.

About Declare OnChange rules

Create Declare OnChange rules to run an activity automatically at activity step boundaries when the
value of a specified property changes. This capability provides a form of automatic forward chaining.

Declare Trigger rules

To define correlations between events in your case types, create Declare Trigger rules to cause an
activity to run when a specified event takes place in a case. By creating Declare Trigger rules, you
automate your business processes and flexibly respond to dynamic business needs.

Defining conditions in the condition builder

Use the condition builder to create conditions that define the behavior of your application, or to use for
propositions evaluated by a proposition filter. You can save custom conditions to the condition library
for future use.

Building expressions with the Expression Builder

Author expressions using the Expression Builder by completing the following steps:

Data transforms
A data transform defines how to convert data that is in one format and class (the source) into data of
another format and class (the target). The supported formats are clipboard and JSON. Using a data
transform instead of an activity to set property values speeds up development and makes application
maintenance easier.

The two main types of data transforms are the standard data transform and the JSON data transform. When
you want to convert data formats, use the standard data transform to manage your application data within
internal Pega Platform applications. When you need to integrate disparate data , for example, web-based
data with information provided by internal sources, use the JSON data transform.

For more information about configuring a data transform, see the following topics:

Configuring a data transform

Configuring the JSON data transforms settings column
Unit testing a data transform

Data transforms are useful in the following situations:

When using data pages to manage application data (see the Where referenced section below).
In activities (see the Access section below).

You can create a data transform for either a clipboard or JSON model format. You select the type of data
transform in the Additional configuration options section on the Create Data Transform form. The
options are different depending on which model format you choose.

For the JSON model format, you can choose whether to automatically map all data in the JSON string, or
you can map individual properties. Mapping individual properties is useful when you have a large JSON
string and you only care about a couple of properties, when you want to change the JSON structure, and
when the fields in the JSON have different names from the clipboard properties to which you are mapping.
In addition, you can select classes to exclude.

Mapping JSON elements to multiple clipboard properties

If you map a single JSON element to multiple clipboard properties in a JSON data transform, the system sets
the value from the JSON element on the last property. This behavior applies to properties that are included
within the same hierarchy level.

For example, you set an Append and Map to action in your JSON data transform and configure two
properties, .CardName and .CardName2. You set both properties to the "name" JSON element. If you run
the JSON data transform in deserialization mode, only .CardName2 is set to "name" because it is the latter
property in the set action.

Example of mapping the same JSON element to multiple properties

Conversely, you configure two properties called .CardName, and set one property to the “name” JSON
element and the other property to the “name2” JSON element. If you run the JSON data transform in
serialization mode, the system sets the value of .CardName to “name2” because “name2” is the latter field
in the set action.

Example of mapping different JSON elements to the same property

Where referenced
The following data transforms that are used for data management use data pages:

Optional data mapping on the property form – On the Edit Property form, the Optional Data
Mapping field appears when you select Copy data from a data page . Use this data transform to
copy a subset of the data from the data page to the property. If you do not specify a data transform,
the system copies all of the data from the data page to the property.
Request data transform – When a data source for a data page is a connector (an integration with an
external data service), the request data transform lets you map Pega Platform data to the fields that
the connector needs to communicate with the data service. Select the data transform to use in the
Request Data Transform field on the Data Page rule form on the Definition tab, in the Data
sources section.
Response data transform – Response data transforms normalize data provided by the data sources
into the common application data model. A response data transform is required when the data source
class is incompatible with the data page class (the recommended pattern to achieve true data
virtualization). Select the data transform to use in the Response Data Transform field on the Data
Page rule form on the Definition tab, in the Data sources section.

Other parts of Pega Platform that reference data transforms include:

Several activity methods that operate on pages can use a data transform, such as the Apply-
DataTransform, Apply-Model (deprecated), Page-New, Page-Copy, and Page-Change-Class methods.
Starter flows, flows that create work items, can specify a data transform (on the flow's Process tab)
for a Work- class to set initial properties for the work item.
 The Action tab for a flow action can specify that the system apply a data transform before or after
displaying the flow action user interface to the user.
For flows that have been edited by using the Flow form, data transforms can be specified on the Set
Properties tab of the Connector Properties panel.
In various user interface elements, which include the Client Event Editor's:
Refresh This Section action
Refresh When conditions
On-click control rule actions Refresh Section, Show Harness, and Open URL In Window

Data transform rules can be referenced by other data transforms.

Rule types that create clipboard pages (such as Connector rules, Service rules, and other rule types) can
use data transforms.

Actions
For more information about a specific data transform action, see the following topics:

Append and Map To

Otherwise When
Append To
Remove
Apply Data Transform
Set
Auto-map
Sort
Exit For Each Page
Update Page
For Each Page In
When
Otherwise

Action restrictions
The following property types have limited support in data transforms and have no support in JSON data
format transforms:

Page Groups
Value Lists
Value Groups

Access
Use the Application Explorer to access data transforms that apply to the work types in your application. Use
the Records Explorer to list all data transforms available to you.

Category
Data transform rules are part of the Data Model category. A data transform is an instance of the Rule-Obj-
Model class.

Data Transforms - Completing the Create, Save As, or Specialization form

Configuring a data transform

To make application development maintenance more convenient and efficient, set property values by
using data transforms. When you create a data transform, you convert data from one format and class
to another format and class.

Data Transform form - Append and Map to action

Use the Append and Map to action to append a page to the target Page List mode property and set the
context to that page for subsequent child actions to map properties on that page. The target and
source can be of different Applies To classes.

Data Transform form - Append to action

Data Transform form - Apply Data Transform action
 Use the Apply Data Transform action to apply actions defined in another data transform (the applied
data transform).

Data Transform form - Auto-map action

Use the Auto-map action to contextually and automatically map data from JSON to the clipboard or
from the clipboard to JSON.

Data Transform form - For Each Page In and Exit For Each actions
Data Transform form - Remove action
Data Transform form - Set action

Use the Set action to set the target equal to the source. When you specify a target page that does not
yet exist on the clipboard, the Set action creates the page.

Data Transform form - Sort action

Data Transform form - Update Page action

Use the Update Page action to set values on a target page that is different from the data transform's
primary page.

Data Transform form - When, Otherwise, and Otherwise When actions

Configuring the JSON data transforms settings column on the Data Transform form

Pega Platform displays the Settings tab on the data transform rule form for the JSON data model
format. Use the Settings tab to enable multidimensional array output and to specify fields to skip
during auto-mapping. You might want to skip fields that do not have meaning outside of Pega
Platform, such as pyObjClass.

Data Transform form - Completing the Pages & Classes tab

To use page names in fields on the Definition tab, you must specify those pages on this Pages &
Classes tab.

Adding data transform to a process

To save time, define a place in your case where a data transform occurs by adding the data transform
to a process. You typically add a data transform between two assignments. For example, while
processing a purchase order, you can populate a shipping address with data that a user provides as a
billing address.

Standard Data Transforms

More about data transforms

Using a data transform, you can specify initial properties for objects of a specific class and also map
properties (and their values) of an instance of a class to an instance of a different class.

Unit testing a data transform

You can use the Run Rule feature to test a data transform individually before testing it in the context
of the application that you are developing. Additionally, you can convert the test run into a Pega unit
test case.

Creating unit test cases for rules

Data Transforms - Completing the Create, Save As, or

Specialization form
Records can be created in various ways. You can add a new record to your application or copy an existing
one. You can specialize existing rules by creating a copy in a specific ruleset, against a different class or (in
some cases) with a set of circumstance definitions. You can copy data instances but they do not support
specialization because they are not versioned.

Based on your use case, you use the Create, Save As, or Specialization form to create the record. The
number of fields and available options varies by record type. Start by familiarizing yourself with the generic
layout of these forms and their common fields using the following Developer Help topicsusing the following
Developer Help topics:

Creating a rule
Creating a rule specialized by circumstance
Creating a rule or data instance
Creating a specialized or circumstance rule

This information identifies the key parts and options that apply to the record type that you are creating.

Create a data transform rule by selecting Data Transform from the Data Model category.

A data transform rule has two key parts:

Field Description

Select a class that this data transform applies to.

Apply
The list of available class names depends on the ruleset that you select. Each class can restrict
to
applying rules to an explicit set of rulesets as specified on the Advanced tab of the class form.

Enter a name that is a Java identifier. Begin the name with a letter, and use only letters,
numbers, and hyphens. See How to enter a Java identifier.
Name
A conventional name for the initial, and typically the simplest, data transform in a class is pyDefault.
This name is not reserved and has no special significance.

Data transforms
Unit testing a data transform
More about data transforms

Configuring a data transform

To make application development maintenance more convenient and efficient, set property values by using
data transforms. When you create a data transform, you convert data from one format and class to another
format and class.

For example, if a customer enters a shipping address on an order form, you can configure a data transform
to populate the billing address with the same details.

1. In the header of Dev Studio, click Create Data Model Data Transform .
2. In the Label field, enter a short description for your data transform.
For data transforms that initialize cases, use the pyDefault name.
3. Optional: To manually set the identifier of your data transform, in the Identifier section, click Edit.
By default, the system automatically populates this field with a read-only value that is based on the
sentence that you enter in the Identifier section. The system ignores spaces and special characters.
4. In the Additional configuration options section, select a data model format for your data
transform:
If you want to use the Clipboard tool as your data model, select Clipboard.
If you want to use JSON as your data model, select JSON.
5. In the Context section, specify the Pega Platform ruleset context for your data transform:
a. Select an application layer in which you want to store the record.
b. In the Apply to field, select the class to which this data transform applies.
c. In the Add to ruleset field, select the name of a ruleset to which you want to add the record, and
then, in the list, select the version number.
6. Optional: To override the default work item that your application associates with this development
change, in the Work item to associate field, press the Down arrow key, and then select a work item.
For more information about default work items, see Setting your current work item.
7. Click Create and open .
8. On the Definition tab, configure details of the data transform, based on the selected data model:
Choices Actions

a. In the Action column, select an action that you want to perform on the
data.
 Choices For more information aboutActions
actions available for the Clipboard tool,
see Data transform actions for Clipboard.
b. In the Target column, specify the target of the selected action.
c. If available, in the Relation column, specify the relationship between
the target and the source.
Configure the data The Relation column will show available selections based on the
transform by using the action selected in step a.
Clipboard tool d. In the Source column, specify the source of the selected action.
e. Optional: To add more actions in your data transform, click Add a
row, and then repeat steps 8.a through 8.d.
f. Optional: To chain together this data transform and data transforms
with the same name in any of its parent classes, select the Call
superclass data transform check box.
At run time, the system first performs the actions in the highest-level
data transform.

a. Select the Auto-map all data check box. Result: At run time, the
system maps the JSON string to the clipboard.
Auto-map the data b. In the Top element structure section, select whether the structure
transform by using for your data transform is an object or an array.
JSON c. If your element structure is an array, in the Pagelist Property field,
select the property to which to map the array, and then select the
JSON elements.

a. In the Top element structure section, select whether the structure

for your data transform is an object or an array.
b. If your element structure is an array, in the Pagelist Property field,
select the property to which to map the array, and then select the
JSON elements.
c. In the Action column, select an action that you want to perform on the
data.
For more information about actions available for JSON, see Data
transform actions for JSON.
d. In the Clipboard column, select the clipboard value to use for JSON
serialization or deserialization.
e. If available, in the Relation column, specify the relationship between
the target and the source.
The Relation column will show available selections based on the
action selected in step a.
f. In the JSON column, enter the array, object, or simple field name from
Configure the data the JSON data.
transform by using g. In the Empty behavior column, control the mapping results of a JSON
JSON data transform by selecting an empty behavior.
The configuration choices include the following options:

Default value
The JSON data transform serializer maintains the preexisting
value. This configuration supports backward compatibility with
Pega Platform that are earlier than 8.5.
Null
Represents a null value in the JSON data transform when the
associated ClipboardPage / ClipboardProperty exists with an
empty value,
Skip
Skips mapping in JSON when the associated ClipboardPage /
ClipboardProperty exists with an empty value.

h. Optional: To add more actions to your data transform, click Add

element, and then repeat steps 8.c through 8.g.
9. Optional: To hide all child rows, click Collapse All.
10. Optional: To show all child rows, click Expand All.
11. Click Save.

Data transform actions for Clipboard

 To save time while processing your cases, populate data in your application by using data transforms.
When you use data transforms, you can convert data from one format and class to another format and
class.

Data transform actions for JSON

Save time while processing your cases by providing data for your application through data transforms.
When you apply a data transform, you populate target values with values form a source that you
specify, so that you avoid providing the same data twice.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data transform actions for Clipboard

To save time while processing your cases, populate data in your application by using data transforms.
When you use data transforms, you can convert data from one format and class to another format and
class.

When you configure a data transform using the Clipboard data model, you select an action that you want to
perform on the data. You can select the following actions:

Set
Sets the target to equal the source. You can set single-value properties, top-level pages, embedded
pages, page lists, and page groups. You typically use this action to initialize properties. If the target
pages that you specify do not exist on the clipboard, the Set action creates the pages.
Remove
Deletes the target and any associated values from the clipboard.

Update Page
Sets the context for setting properties on the target page. Use to set properties on a page that is
different from the primary page. If the target page does not already exist on the clipboard, the system
creates the page. If the source page is different from the primary page, from the Relation list, select
with values from, and then specify the source page.
Apply Data Transform
Applies another data transform to a clipboard page that the previous action specifies in the current
context.
Sort
Creates custom ordered lists. You can sort a page list according to single-value properties in that page
list. You can specify a sorting order for each property as either ascending or descending order. In the
Target column, click the View Sorting Properties icon to specify the properties on which to sort and the
sorting order for each property.
Comment
Specifies descriptive text. Use this action to provide comments within the sequence. For example, you
can explain the goal of a branch of steps.

When
Specifies a condition to evaluate to determine whether to apply the subsequent actions. If the
condition evaluates to true, the system applies the action within the child rows. If the condition
evaluates to false, the system continues with the action specified within the next row. If the action in
the next row is Otherwise or Otherwise When, the system applies the action if the condition evaluates
to true.
Otherwise When
Specifies another condition to meet before the system applies an alternate condition. If the condition
evaluates to true, the system applies actions within the child rows. If the condition evaluates to false,
the system continues with the action specified within the next row. You can use this action after you
use a When or Otherwise When action.
Otherwise
Specifies the alternate actions to apply if the preceding When or Otherwise When action evaluates to
false. You can only use this action after a When or Otherwise When action.Note: If you add When,
Otherwise When, and Otherwise actions to your data transform, the system performs only one of these
actions, depending on the first of these actions that evaluate to true.
Append to
Copies a page to the target. You can copy a page if the source and the target are of the same class, or
 if one of the classes is higher in the class hierarchy in the inheritance path.
Append and Map to
Adds a page to the target and maps properties and their source values to the target properties. The
source and target can be of different classes.
For Each Page In
Iteratively applies actions specified in the subsequent rows to all the pages in the specified target.
Ensure that the target is a Page List or a Page Group.
Exit For Each
Exits the current iteration defined by the preceding For Each Page action. You can use this action only
as a child row of a For Each Page In action.
Exit Data Transform
Stops the data transform at the row that contains the Exit Data Transform action.

Standard Data Transforms

Data transform actions for JSON

Data transform actions for JSON

Save time while processing your cases by providing data for your application through data transforms.
When you apply a data transform, you populate target values with values form a source that you specify,
so that you avoid providing the same data twice.

When you configure a data transform by using JSON, you select an action that you want to perform on the
data. You can select the following actions:

Set
Sets the target to equal the source. You can set single-value properties, top-level pages, embedded
pages, page lists, and page groups. You typically use this action to initialize properties. If the target
pages that you specify do not exist on the clipboard, the Set action creates the pages.
Auto-map
Automatically maps the JSON data to the clipboard.
Update page
Sets the context for setting properties on the target page. Use to set properties on a page that is
different from the primary page. If the target page does not already exist on the clipboard, the system
creates the page. If the source page is different from the primary page, from the Relation list, select
with values from, and then specify the source page.
Append and Map to
Adds a page to the target and maps properties and their source values to the target properties. The
source and target can be of different classes.
Apply data transform
Applies another data transform to a clipboard page that the previous action specifies in the current
context.
Comment
Specifies descriptive text. Use this action to provide comments within the sequence. For example, you
can explain the goal of a branch of steps.

Standard Data Transforms

Data transform actions for Clipboard

Data Transform form - Append and Map to action

Use the Append and Map to action to append a page to the target Page List mode property and set the
context to that page for subsequent child actions to map properties on that page. The target and source
can be of different Applies To classes.

Usage
The Append and Map to action is equivalent to doing an Update Page action using the <APPEND>
keyword. When the system invokes the Append and Map to action, it creates a new page in the target
Page List property, without creating any embedded properties in that new page. Subsequent child actions
create the embedded properties on the page.

When you select the Append and Map to action, the system automatically displays a child Set action
because no properties exist yet on the newly created page.

When you use a source that is a Page List or a Page Group property (using the each page in choice for the
Relation), the When icon appears next to the each page in choice. Click this button to specify a when condition
rule for the Append and Map to action, so that a page from the source is appended to the target only if
the condition is true. For example, when your target is a Page List property of PreferredCustomers, and you
want to map data from an AllCustomers source Page List property only for those customers that are
"preferred" customers, click the When icon and specify a when condition rule named IsPreferred.

JSON data model format

When the data model format for a data transform is JSON, there are the following differences in behavior
from the clipboard data model format:

The order of the steps is not guaranteed.

The data transform is bidirectional and can be called in either direction using the executionMode
parameter. This parameter indicates whether to use JSON as the source and the clipboard as the
target or use the clipboard as the source and JSON as the target.
There are two parameters for the JSON transform. JSON transforms cannot have custom parameters.
jsonData – Specifies the incoming or outgoing JSON data
executionMode – Specifies the direction of the transform, SERIALIZE or DESERIALIZE.
The Pages & Classes tab is only used to specify the class of classless properties, such as pxResults.
JSON data model format transforms cannot reference other top-level pages. You can only reference
fields on the primary page.

In addition, the JSON field requires a JSON array name.

Example
Append and Map to pyWorkPage

Relationship settings
The following relationship settings are available when the data model format is clipboard:

a new page – The default. Use to create a new page in the target Page List, and subsequently create
properties on that page.
an existing page – Use to create a new page in the target Page List, and subsequently create
properties on that page that are to be mapped from a source page.
each page in – Use to create a new page in the target Page List, and subsequently create properties
on that page that are to be mapped from a source Page List or Page Group.

The following relationship settings are available when the data model format is JSON. Select the setting that
matches the structure of the JSON array.

An array of objects – This is the only option that translates directly to the clipboard. There are no
restrictions on the number of child steps or siblings.
An array of scalars – In JSON, an array of scalars has the format [1,2,3,...] or ["a","b","c",...]. When
you choose this option, there is exactly one child step for the Append and Map to step. You cannot
add siblings or disable the step. The step is a set step and the JSON side states, "each scalar element."
You can specify the clipboard field to map to.
An array of arrays – In JSON, an array of arrays has the format [[...],[...],...], where each element is a
nameless array. When you choose this option, there is exactly one child step for the Append and
Map to step. You cannot add siblings or disable the step. The child step can have either an Auto-map
or Append and Map to action. The JSON side states, "each array element." You can pick a Page List
for the clipboard side. If you add an Append and Map to step, the same options are available again
(array of objects, array or scalars, and array of arrays), so that you can configure embedded child
steps.
A group of pages – Select this option to configure mapping to a property that contains an unordered
group of embedded pages. You can map a group of pages in either direction, from the source to the
target or the reverse. When you choose this option, you can set child steps to map the data for the
Append and Map to step. You can add siblings, disable the steps, and perform the full set of actions
available in the Action column.
Supported features
You can use the following items in the Append and Map to action:

In the Target column, Page List mode properties

In the Source column, Page, Page List, and Page Group mode properties
Conditionalizing the Append and Map to action, when the source is a Page List or a Page Group
(using the When icon)

Restrictions
You cannot specify a Page Group mode property as the target for the Append and Map to action. That is,
you cannot append to a Page Group mode property by using this action.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Append to action

Usage
Use the Append to action to copy a page from the source to the target, or to copy all of the elements in a
source Page List property to a target Page List property. The target must be of a class that is compatible
with the source page. (To append a page to a target having a class that is not compatible with the source's
class, or to conditionally map source data, use the Append and Map to action.)

Example
In this example, Shipments and ShipmentGroup are properties having the same Page Class. Shipments is a Page List
property, and ShipmentGroup is a Page Group property. The Append to action specifies to copy each page from
ShipmentGroup to Shipments.

Append to .Shipments each page in .ShipmentGroup

Relationship settings
a new page — The default. Use when you want to create a new page in the target Page List property.
an existing page — Use when you want to copy a source page as the new page in the target Page List
property.
— Use when you have a Page List or Page Group for the source, and want to copy pages in
each page in
the Page List or Page Group as new pages in the target Page List.

Supported features
You can use the following items in the Append to action:

In the Target, Page List mode properties

In the Source, Page, Page List, and Page Group mode properties

Restrictions
You cannot specify a Page Group mode property as the target for the Append to action. That is, you cannot
append to a Page Group mode property.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Apply Data Transform action

Use the Apply Data Transform action to apply actions defined in another data transform (the applied
data transform).

Usage
To apply the data transform to a specific page, specify a row by using an Update Page action before the
Apply Data Transform action row. To apply the data transform to a specific page, precede the Apply
Data Transform action with an Update Page action to identify the page.

JSON data model format

When the data model format is JSON, there are the following differences in behavior:

The order of the steps is not guaranteed.

The data transform is bidirectional.

Relation column
The Apply Data Transform action has no setting for the Relation field.

Parameters in the to-be-applied data transform

The applied data transform can have parameters defined on its Parameters tab. In the Apply Data
Transform action row, click the View Data Transform Parameters icon to provide values for the applied
data transform's input parameters (if any), or specify whether to pass the current parameter page.

When the Pass current parameter page? check box is selected, the two data transforms (the one that
has the Apply Data Transform row and the applied data transform specified in that row) share one
parameter page. If the check box is not selected, the parameters on the parameter page for the applied
data transform are not available to the other data transform, and vice versa.

If the current parameter page is shared, and the applied data transform has a parameter declared as Out, if
the applied data transform updates the value of that parameter, the resulting value is available to the other
data transform.

Note: If the data transform that you are calling changes any values on the parameter page, those values
will be lost if you do not select the Pass current parameter page? check box. For example, when calling
a JSON data transform using the SERIALIZE value for the executionMode parameter, the resulting JSON data
is written to the parameter page as a value of jsonData.

Restrictions
You cannot call a clipboard data transform from a JSON data transform.

You cannot use the Top or Parent keywords in the entry field when specifying the applied data transform.

You cannot use expressions when specifying the applied data transform.

When $ANY is used in the entry field (to make the class of the applied data transform assignable at run
time), design-time validation does not check whether the specified data transform exists when you save
this data transform form.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Auto-map action

Use the Auto-map action to contextually and automatically map data from JSON to the clipboard or from
the clipboard to JSON.

Usage
Use the Auto-map action with a Page or Page List property that has a data model of the property's page
class that exactly matches the JSON data model. The name and type of every child field is the same in both
the JSON data and the clipboard.

Note: To ensure that the Auto-map action runs properly, as a best practice, define the desired Pega
Platform data model in your application hierarchy.

For more information about mapping and JSON serialization and deserialization, see the following articles
on Pega Community:

Using the mapping API for high-performance JSON serialization

Using the mapping API for high-performance JSON deserialization

Relation column
The Auto-map action has a fixed Relation field setting of To. That is, the Auto-map action always sets the
target to the source and establishes no other sort of relationship between the two.

Note: When serializing JSON, the source is clipboard, and when deserializing JSON, clipboard is the target.

Restrictions
The only property type values supported are:

Page
Page List

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - For Each Page In and Exit For Each
actions
Usage
Use the For Each Page In action to have the system apply the subsequent actions to every page in a target
Page List or Page Group mode property. After the For Each Page In action row, the system goes down the
subsequent children rows and iteratively applies the actions in those rows to each page in the target.

Use the Exit For Each action to stop the iterations of the For Each Page In action. Actions at the same level
as the Exit For Each row (its siblings) are not performed by the system.

The Exit For Each action is typically used as part of an overall conditional structure. For example, in the
following shopping cart example, Items is a Page List property. if the user adds a product item
(.PRODUCTNAME) and quantity to his shopping cart, the When action checks to see if that product is
already in the cart, for each page of Items and if so, updates the quantity in the shopping cart with the
additional quantity for that item. After the item is found in the cart, the Exit For Each action stops the
system from iterating over the rest of the pages in Items and omits the actions for the Otherwise case (which
are not needed once the item is found to exist in the cart).

For Each Page In pyWorkPage.Items

When .Name == Primary.PRODUCTNAME
Set pyWorkPage.ItemToAdd.LocationFound equal to pyWorkPage.Items(<CURRENT>).pxListSubscript
Set pyWorkPage.ItemToAdd.Found equal to "true"
Set pyWorkPage.ItemToAdd.Quantity equal to pyWorkpage.Items(<CURRENT>).Quantity
Exit For Each
Otherwise
Set pyWorkPage.ItemToAdd.Found> equal to "false"

Example
For Each Page In .Customers
When IsPreferred
Set Discount equal to 15
Otherwise When IsExisting
Set Discount equal to 5

Relationship settings
The For Each Page In and Exit For Each actions have no settings for the Relation field.

Supported features
You can use the following items in the For Each Page In action:

Page Lists
Page Groups
Parameters specified as Page Name

Restrictions
You cannot use Page List properties that have Lightweight specified in their rule forms as sources.

You cannot iterate over a source. You can only iterate over target pages.

You cannot use the <APPEND> keyword in the For Each Page In action. Instead, follow the For Each Page
action with an Append to action or Append and Map to action.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Remove action

Usage
The Remove action deletes the specified target and any associated values from the clipboard.

Example
Remove pyWorkPage.ItemToAdd.Quantity

Relationship settings
The Remove action has no setting for the Relation field.

Supported features
You can use the following items in the Remove action:

Properties
Pages (top-level or embedded clipboard pages)
Page Lists
Page Groups
Value Lists
Value Groups
Data pages (pages created by data page rules).
Primary keyword and a property (for example, Primary.Firstname )

Restrictions
To remove a top-level page, the page must be specified on the Pages & Classes tab.
You cannot use Top, Parent, or param in the Remove action.

You cannot remove the primary page (the page of the Applies To class of the data transform).

You cannot remove a parameter (specified on the Parameters tab).

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Set action

Use the Set action to set the target equal to the source. When you specify a target page that does not yet
exist on the clipboard, the Set action creates the page.

Usage
To select a value for the target property from the set of values defined in case instances for the property,
click Select values.

JSON data model format

When the data model format is JSON, there are the following differences in behavior:

The order of the steps is not guaranteed.

The data transform is bidirectional.

Examples
Set .pyWorkIDPrefix equal to "W-"
Set .HardwareItems(1).Price equal to ""

Relation column
The Set action has a fixed Relation setting of equal to . That is, the Set action always sets the target equal to
the source, and establishes no other sort of relationship between the target and source.

Note: When serializing JSON, the source is clipboard, and when deserializing JSON, clipboard is the target.

Supported features clipboard data model format

When the data model format is clipboard, the Set action supports the target and source combinations
shown in the following table. These features are not supported when the data model format is JSON.

The class of the target does not have to match the class of the source.

Target Relation Source Example

Single Value Property equal to Property Reference .Department

Single Value Property equal to Literal "W-"

Single Value Property equal to Expression .FIRSTNAME + " " + .LASTNAME

Single Value Property equal to Linked Property Reference .pxCreateOperator.pyUserName

Page equal to Page OrderItems(1) equal to HardwareItems(1)

The source and target support the following items:

Properties
Literals
Expressions (in the source column only)
 Parameters specified on the Parameters tab (for example, param.Name )
Page Lists
Page Groups
Value Lists
Value Groups
Keywords: Primary, <APPEND>
Function calls (in the source column only )

When the Set action is preceded by an Update Page, the context of the source is reset and all property
references are relative to the new page.

Restrictions
The use of Top and Parent keywords is not supported.

You cannot set properties on data pages. Such properties cannot be specified as targets.

References to linked properties are read-only. Such properties can be specified as sources, but not as
targets.

You cannot set reference properties (properties that have the Reference Property check box selected on
the Advanced tab of their Property forms). They cannot be specified as targets.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Sort action

Usage
Use the Sort action to create custom ordered lists. A typical scenario is you are displaying a multi-column
list and you want the columns automatically sorted according to values in one or more of the columns. With
the Sort action, you can sort a Page List property according to single-value properties in that Page List. For
each single-value embedded property, you can specify sorting in either ascending or descending order of
that property. Click the View sorting properties icon to specify the properties on which to sort and the
sorting order for each property.

If you specify more than one embedded property to sort on, the first property specified is given precedence
at runtime. For example, you want a section to display a list of product items in an order, and the page list
is Items, with embedded properties:

Quantity (Integer type)

TotalPrice (Decimal type)

And you want to show the user the list of items sorted first by quantity from smallest to largest, and then by
total price from highest to lowest within a given quantity. In the Sort By Property window, specify the Quantity
property in ascending order and the TotalPrice property in descending order.

At runtime, the displayed rows run from the lowest quantities to the highest, and rows that have the same
quantity are displayed with the highest total price first, then the next, and so on.

Relationship settings
The Sort action has no setting for the Relation field.

Supported features
You can use the following items in the Sort action:

In the Target, Page List mode properties

As the embedded properties on which to sort by, single-value properties. For each sorted-by property,
you can sort in ascending or descending order.
Restrictions
You cannot specify a Page Group mode property as the target for the Sort action. That is, you cannot sort
by properties in a Page Group mode property.

You cannot sort by properties in the Page List that are not single-value properties. For example, you cannot
sort by a Page property in a Page List property.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Update Page action

Use the Update Page action to set values on a target page that is different from the data transform's
primary page.

Usage
The Update Page action sets the page context for the subsequent (children) steps. Using the Update
Page allows you to:

Avoid entering the target page name each time in the children Set actions
Use source values from a page that is different from the data transform's primary page

For example, the following data transforms are equivalent:

Set pyWorkPage.CustomerType equal to "Existing"

Set pyWorkPage.CustomerLevel equal to "Bronze"

and

Update Page pyWorkPage

Set .CustomerType equal to "Existing"
Set .CustomerLevel equal to "Bronze"

In the second example, the Update Page action sets the page context to the pyWorkPage , so that the
page does not have to be specified for the Target fields in the following child steps.

You can set the page context for the target only, or for both the target and source. To set the page context
for the source, select with values from in the Relation field.

JSON data model format

When the data model format is JSON, there are the following differences in behavior:

The order of the steps is not guaranteed.

The data transform is bidirectional.

In addition, the JSON field requires a JSON object name.

Examples
Update Page pyWorkPage
Set .ZipCode equal to "02139"
Set .TelPrefix equal to "617"
Update Page pyWorkPage with values from Employees
Set .ZipCode equal to .PostalCode
Set .TelPrefix equal to .Prefix

Relation column
The following relationship settings are available when the data model format is clipboard:
 blank – The default. Use when setting values on a target page using source values that are on this
data transform's primary page (the clipboard page with the same class as the data transform's
Applies To class).
With values from – Use when the source values are on a page other than the data transform's
primary page.

The following relationship settings are available when the data model format is JSON:

For both sides – Set the page context for both the JSON and clipboard sides.
For JSON only – Set the page context for the JSON side only.
For clipboard only – Set the page context for the clipboard side only.

JSON relationship settings example

This example illustrates how to use the relationship settings. The JSON for a customer is as follows:

{
"id": 123456,
"name": "John Doe",
"email": "john.doe@example.com",
"address": {
"addressLines": {
"line1": "1 example st",
"line2": "example building"
},
"city": "Example",
"zip": "02142"
}
}

The clipboard structure is as follows:

Customer
ID
Name
Email
Address
AddressLine1
AddressLine2
City
Zip

The tree structures match except for the address line fields. line1 on the JSON side is under the address >
addressLines hierarchy, but its corresponding AddressLine1 property on the clipboard is directly under Address . In
this case, use the Update Page action to update context only on one side. To map the entire structure,
update the context for address on both sides, then update the context only on the JSON side, and then map
individual properties, as shown in the following sample:

Update Page Address For both sides address

Update Page No context change For JSON only addressLines

Set AddressLine1 equal to line1

Supported features
You can use the following items in the Update Page action:

Page (top-level or embedded clipboard page)

Page in a Page List
Page in a Page Group
Keywords: <APPEND> , <LAST>, Primary
Expressions in the index (subscript) of an aggregate property

Restrictions
 You cannot use the Parent keyword.
Do not use the Top keyword in data transforms. In some situations, using Top does not work if a top-
level page is not clearly defined (for example, if a row has both source and target pages).
You cannot use data pages (pages that are instances of data page rules).

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - When, Otherwise, and Otherwise When

actions
Usage
Use the When, Otherwise, and Otherwise When actions to conditionalize data transform actions, so that the
system invokes the actions only when the specified conditions are true.

For example, given an ordering process with a form where customers can select a check box to indicate
whether their billing address is the same as their shipping address, you can use a When action to tell the
system to perform a set of actions (children actions of the When) when that check box is selected (
BillAddressSameAsShipping property is true). By using an Otherwise action after the When action, you can specify
another set of data transform actions to take if the check box is not selected.

In the list of rows on the Definition tab, an Otherwise When action row must be preceded by a When action
row at some point in the list. An Otherwise action row must be preceded by either a When action row or an
Otherwise When action row.

Example
In the following example, if the user selects Billing address same as shipping address check box in the
order form, the property BillingAddressSameAsShipping is set to "true". In that case, the data transform actions
following the When action specify to update the pyWorkPage.pyWorkParty(Customer).BillingInformation page using the
Address value from the pyWorkPage.pyWorkParty(Customer).ShippingInformation page (that is, use the shipping address
for the billing address). If the check box is not selected, the children actions of the Otherwise action specify
to set the billing information page values to null strings, so that the user has to enter the data.

When pyWorkPage.pyWorkParty(Customer).BillingAddressSameAsShipping == "true"

Update Page pyWorkPage.pyWorkParty(Customer).BillingInformation with values from pyWorkPage.pyWorkParty(Customer).ShippingInformation
Set .Address equal to .Address
Otherwise
Update Page pyWorkPage.pyWorkParty(Customer).BillingInformation
Set .Address equal to ""

Relationship settings
The When, Otherwise, and Otherwise When actions have no settings for the Relation field.

Supported features
You can use the following items in the rows for the When and Otherwise When actions:

When condition rules

Expressions
Primary keyword

Restrictions
Do not use < or > in an expression. Use <= or >= instead.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms
Configuring the JSON data transforms settings column on the
Data Transform form
Pega Platform displays the Settings tab on the data transform rule form for the JSON data model format.
Use the Settings tab to enable multidimensional array output and to specify fields to skip during auto-
mapping. You might want to skip fields that do not have meaning outside of Pega Platform, such as
pyObjClass.

Before you begin: Create a data transform with a JSON data model format. For more information, see
Configuring a data transform.

1. In the data transform that you create, click the Settings tab.
2. To enable multidimensional array output, select the Enable multidimensional array output check
box.
Select this option when auto-mapping is enabled on the Definition tab and you have a Page List
property with only one non-skipped property that has the same name as its parent. If you enable
multidimensional array output, the Page List property will result in a multidimensional array in the
JSON output. If you do not select the Enable multidimensional array output check box, the Page
List property is displayed as an array of objects.
For example:

Multidimensional array option enabled

Clipboard page Resulting JSON
.pxResults(1) {
.pxResults(1) pxResults: [[{
.Name = “John Smith” Name: “John Smith”
}]]
}

In this example, the pxResults field in the JSON output has two array characters, denoting the
output as an array of arrays.

Multidimensional array option disabled

Clipboard page Resulting JSON
.pxResults(1) {
.pxResults(1) pxResults: [{
.Name = “John Smith” pxResults: [{
Name: “John Smith”
}]
}]
}

In this example, the output is an array of objects, in which each element has a pxResults field.

3. In the Date format for serialization field, select the output format to use when serializing a data
page:
When you select Pega API, the system formats the output as:

Date: 1996-07-26

Date Time: 1996-07-26T09:30:00.000Z

Time of Day: 09:30:00.000Z

When you select Pega Internal, the system formats the output as:

Date: 19960726

Date Time: 19960726T093000.000 GMT

Time of Day: 093000

4. To specify which fields to skip processing during auto-mapping, in the Fields to skip when auto-
mapping section, click Add field to add a field to the list.
5. To specify the default auto-map empty behavior, select an empty behavior in the Default Automap
Empty Behavior field.
 Note: Select this option when the Auto-map all data check box is selected on the Definition tab.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Data Transform form - Completing the Pages & Classes tab

To use page names in fields on the Definition tab, you must specify those pages on this Pages & Classes
tab.

At runtime, the system uses information from this tab to locate properties on the clipboard.

Specifying the pages on the Pages & Classes tab also assists when working with the Definition tab at design
time. For example, when a page is specified here, it is listed in the SmartPrompts in the fields on the
Definition tab.

See How to Complete a Pages & Classes tab for more details.

Note: For JSON data model format transforms, this page is only used to specify the class of classless
properties, such as pxResults.

Click the Add item icon to add new rows to the array. Click the Delete icon to delete a row.

Field Description

Page
Enter the name of a clipboard page referenced on the Definition tab.
Name

Specify the class of that page. Click the Open icon to open the class rule, or to create the
Class
class if it does not already exist.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

Adding data transform to a process

To save time, define a place in your case where a data transform occurs by adding the data transform to a
process. You typically add a data transform between two assignments. For example, while processing a
purchase order, you can populate a shipping address with data that a user provides as a billing address.

1. In the navigation pane of Dev Studio, click Case types, and then click the case type that you want to
open.
2. On the Workflow tab, hover over a process to which you want to apply a data transform, and then
click Configure process.
3. On the toolbar, click Open process.
4. Double-click a connector between two assignments where you want to add a data transform.
5. In the Connector properties dialog box, in the Set properties section, select Apply data
transform.
6. In the Data transform field, press the Down arrow key, and then select the data transform.
7. Click Submit.
8. Click Save.

Referencing properties
Data transforms

Standard Data Transforms

Naming convention
By convention, the Pega Platform includes a standard data transform named pyDefault for most standard
concrete classes and several standard abstract classes. For example, the Data-Admin-Operator-
ID.pyDefault data transform provides initial values for about 25 properties in the Operator ID data instance.

This is not a reserved name and has no special characteristics. You may create data transforms with this
name or other names in any class or RuleSet.

Data transforms that apply to classes derived from Work-

Whenever a new work item is created, the Pega Platform uses the pyFlowName property in the object to
identify a flow rule to start.

If you create a data transform named pyDefault with the Applies To key part class derived from the Work-
base class, include a value for the pyFlowName property. In most cases, select the Call SuperClass data
transform check box to apply the ancestor pyDefault data transforms also.

Set the value of this property to the Flow Name key part of a flow rule. When a user starts a new flow in the
context of that Work- class, the system uses this value, with rule resolution to find the flow rule to run.

Data
Applies To Purpose
transform

Determines which properties are copied when a user copies a work

Work- pyCopyDefault
item. See Harnesses — How to copy a work item.

Work- pyDefault Provides default initial values for properties in new work items.

Provides default initial values for properties in new work items that
Work-Cover- pyDefault
are covers.

Provides default initial values for properties in new work items that
Work-Folder- pyDefault
are folders.

Provides default initial values for properties in new work items for
Work-.RuleCheckin pyDefault
the rule check-in flow.

PegaSample-
pyDefault Demonstrates entry of a Simple Task work item, not part of a cover.
SimpleTask
PegaSample-
pyDefault Demonstrates entry of a cover work item.
CustomerRequest
PegaSample-Task pyDefault Demonstrates entry of a covered work item.

Data transforms that apply to System-User-MyRules class

By default, the order and link labels for reports in the Monitor Activity work area are controlled by data
transforms with System-User-MyRules as the Applies To key part. Override these standard data transforms
and then modify your rule to reference and label reports as desired.

Applies To Data transform Purpose

System- Determines the order and labels of reports (that are available
User- AssignmentMonitoringReports to all users) in the Monitor Assignments area of the Monitor
MyRules Activity work area.

System-
User- DataReports Not used in PRPC Version 6.
MyRules
System- Determines the order and labels of reports (that are available
User- PerformanceAnalysisReports to all users) in the Analyze Performance area of the Monitor
MyRules Activity work area.

System-
User- RuleReports Not used in PRPC Version 6.
MyRules
 System- Determines the order and labels of reports (that are available
User- WorkAnalysisReports to all users) in the Analyze Process Quality area of the
MyRules Monitor Activity work area.

System- Determines the order and labels of reports (that are available
User- WorkMonitoringReports to all users) in the Monitor Processes area of the Monitor
MyRules Activity work area.

Other standard data transforms

Applies To Data transform Purpose

(various) pyTrackSecurityChanges Affects data retained in history for data objects or rules.

Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

More about data transforms

Using a data transform, you can specify initial properties for objects of a specific class and also map
properties (and their values) of an instance of a class to an instance of a different class.

For example, you can ensure that a special set of risk-related properties is present on all instances of class
Data-Loan-Aircraft-SingleEngine. When a page of this class is created, you can instruct the system to apply
a data transform, named Aircraft-High-Risk. The system places into the page the risk-related properties
defined in the data transform. When the page is later saved into the database as a persistent instance, the
properties are present with meaningful values.

Typically, you use the actions within a data transform to update and apply data to clipboard pages.
Additionally, there are four activity methods that can optionally use a data transform as a parameter:

Apply-DataTransform — Updates existing clipboard pages with values computed from a data
transform.
Page-New — Creates a new named page of a specified class. If a data transform is specified in this
method, the data transform's actions are applied to the page.
Page-Copy — Copies the contents of a clipboard page to a new named page or replaces the contents
of an existing page. If a data transform is specified in this method, the data transform's actions are
applied to the destination page before the source's contents are copied.
Page-Change-Class — Creates a new page of the specified class, and then copies properties from
another page into it, according to the method's Keep parameter and the specified data transform (if
any).

The Apply-Model method is deprecated in version 6.2, and replaced by the Apply-DataTransform method.
To use the Apply-DataTransform method to achieve the same result of using the Apply-Model method with
the OverwriteProperties parameter set to 'false', use When actions in the data transform to prevent values
from being applied when properties are already present on the target page. For example:

When !@PropertyHasValue(.FirstName)
Set .FirstName = "Bob"

In the preceding example, when the FirstName property has a value, the condition is not satisfied and the Set
action is skipped.

Service rules ( Rule-Service- classes) and a few other rule types can reference a data transform. The data
transform is processed and applied at runtime to a newly created page.

Viewing the Java code of a rule

Click Actions View Java to view the generated Java of a rule. You can use the Java code to debug your
application or to examine how rules are implemented.

Changing the value of a TimeOfDay property

When you use an expression on TimeofDay property type values, the expression converts the value into a
BigDecimal where the whole number is the number of days and the fraction is the hour of the day
expressed as a fraction of a day, for example, 12 hours is 0.5 (half of a day). The format is useful to know
when you want to change the value of a property that is a Date, DateTime, or TimeofDayproperty type.

For example, assume that you have a property of type TimeofDaythat is formatted as a standard time with
hour, minute, and second without punctuation. To add 12 hours to the property:

1. Use a Set action to assign the property value to a second property that is of type TimeofDay.
2. On the right side of the expression, enter the property reference plus the fraction. In this example,
enter .5 to add 12 hours.

Constants in expressions
Data transforms
Data Transforms - Completing the Create, Save As, or Specialization form

Unit testing a data transform

You can use the Run Rule feature to test a data transform individually before testing it in the context of
the application that you are developing. Additionally, you can convert the test run into a Pega unit test
case.

1. In the navigation pane of Dev Studio, click Records Data Model Data Transform , and then select
the data transform that you want to open.
2. Click Actions Run .
3. In the Run context pane, select the thread, test page, and data transform you want to use for the
test.
a. In the Thread list, select the thread in which you want to run the rule.
b. In the Page list, select whether to copy parameter values from an existing page or to create an
empty page:

To use parameter values from an existing clipboard page in the selected thread, click Copy
existing page, and then select the page you want to copy.

To start from a page containing no parameter values, click Empty test page.

c. Optional: To apply a data transform, select the Apply data transform check box, and then
select the transform to apply.
Note: The system always runs the rule instance on the RunRecordPrimaryPage, regardless of the
page that you select from this list. If you convert this test run to a test case and the
RunRecordPrimaryPage requires initial values, then configure the clipboard so that it populates
the page with initial values. For more information, see Setting up your test environment.
4. Optional: To change the values that are passed to the rule, provide the new values on the main test
page.
5. Click Run to run the test.
6. To convert the test run into a Pega unit test case, click Convert to test, and then configure the test
case. For more information, see Creating unit test cases for rules.
7. Optional: If the rule has errors, then click Trace to debug it using the Tracer tool. For more
information, see Application debugging using the Tracer tool.
8. Click Clipboard to open the Clipboard and examine the pages that are generated by the unit test. For
more information, see Clipboard pages created by the Run Rule feature.

Data transforms
Viewing test case results
Exporting a list of test cases

Decision tables
Decision tables derive a value that has one of a few possible outcomes, where each outcome can result
from a test of a condition that includes multiple variables. A decision table lists two or more rows, and each
row contains test conditions, optional actions, and a result.

Decision tables are appropriate for evaluations that include more elements compared to simple true/false
evaluations. For example, you can use a decision table to estimate a car insurance payment based on the
age of a driver, age of a car, and make of a car.

You build decision tables by adding columns and rows. Each column represents a condition, while rows
store corresponding values that the system tests at run time. For example, you can build a decision table to
determine shipment costs based on the following conditions:

The value of the order

The weight of the parcel
Whether the shipment is to a foreign country

Each condition is a separate column in the decision table. Additionally, every decision table includes a
column that stores results that the decision table returns if all values in a row evaluate to true.

Each row includes cells that store values that the system evaluates at run time. You can insert more than
one value in a cell by adding an OR condition, and then the system continues processing a row if any of the
values in the cell evaluates to true.

At run time, the system evaluates the rows starting at the topmost row:

If any condition in a row evaluates to false, processing continues with the next row. The system
ignores the Return column for that row.

Note: You can leave empty cells in a row. Empty cells evaluate to true except when a cell is empty
and includes an OR condition. Then, the parser ignores that cell and parses only the cell that contains
a value.

If all the conditions in a row evaluate to true, the system processes the Actions and Return columns
of that row. The next action depends on how you configure your decision table:
To return only one result, you can configure processing to end. The system then returns the value
in the Return column as the value of the entire rule.

In scenarios that require only one result, such as estimating delivery costs, when you end
processing after receiving the first result, you improve performance and avoid unnecessary
computations.

To return multiple results, you can configure processing to continue through all remaining rows,
performing the Actions and Return calculations for any rows for which the conditions are all true.

For example, when the decision table returns the email address of a person in a process to
approve an expense, the expense might require the approval from more than one person, based
on the conditions. Such scenarios require more than one result.

If all rows in the table evaluate to false, the system returns a default result.

For example: In the following figure, the decision table calculates the shipment cost in an online shop. The
cost depends on the value of the order, the weight of the parcel, and whether the shipment is to a foreign
country. If the order value is less than $500, and the parcel weight is less than 3kg, and the shipment is to
the same country, then the shipment cost is $20. If any of these values evaluate to false, the system moves
to the next row. If all rows evaluate to false, the system returns the default value of $60 for the shipment
cost:

Decision table
Applying decision tables
You can apply decision tables in the following elements of your application:

In a flow rule, you can reference a decision table in a decision shape .

For more information, see Adding decisions to processes.

In an activity, you can evaluate a decision tree by using the Property-Map-DecisionTable method.

For more information, see Creating an activity.

A Declare Expression rule can call a decision table.

For more information, see Creating Declare Expression rules.

A collection rule can call a decision table.

Category
Decision table rules are instances of the Rule-Declare-DecisionTable class. Decision tables are part of the
Decision category.

Creating decision tables

To better adjust to the varied factors in your business processes, you can create a decision table.
Decision tables test a series of property values to match conditions, so that your application performs
a specific action under conditions that you define.

Specifying pages and classes of a decision table rule

To ensure that a decision table accesses or updates information on clipboard pages, specify the page
name and class of the pages. At run time, these pages contain the properties that a decision table
references on other tabs of its rule form.

Configuring additional options for a decision table

Adjust how your decision table works by configuring additional options. For example, you can
configure how a decision table behaves after one row evaluates to true, or define which elements of a
decision table are available for edits.

More about Decision Tables

Use a decision table to derive a value that has one of a few possible outcomes, where each outcome
can be detected by a test condition. A decision table lists two or more rows, each containing test
conditions, optional actions, and a result.

Viewing rule history

Creating decision tables

To better adjust to the varied factors in your business processes, you can create a decision table. Decision
tables test a series of property values to match conditions, so that your application performs a specific
action under conditions that you define.
For example, you can define a decision table in your application to calculate a loan interest rate for a
customer. The decision table evaluates the customer's credit score, type of account, and loan term, and
then returns a result that matches values applicable to the customer.

1. Create a rule to store the decision table:

a. In the header of Dev Studio, click Create Decision Decision Table .
b. In the Label field, enter a name that describes the purpose of the table.
c. In the Apply to field, select the class in which you want to create the decision table.
d. Click Create and open .
2. Optional: To prepopulate the decision table with values, upload an .xls file that stores starting
information:
a. In the toolbar, click Import.
b. In the Upload file dialog box, click Choose file.
c. In the Open window, navigate to the file on your local machine, and then click Open.
d. Click Upload file.
For example: You can upload a decision table that stakeholders without access to Pega Platform
prepare offline.
3. On the Table tab, in the Conditions column, click the header cell.
4. In the Decision table property chooser window, in the Property field, enter or select a property
that you want to use as a condition. For example: Enter pyCreditScore.
5. In the Label field, enter the name of the property that you want to display in the header of the
decision table. For example: Enter Credit score .
6. Select a comparison method:
To use a simple comparison, in the Use operator list, select the operator.

For example, select >= to indicate that the value in the decision table must be equal to or greater
than the value that the decision table evaluates at run time.

To specify a range for the condition property, select the Use range check box, and then define
the start and end of a range.

For example, you can configure a property value to be greater than and lower than certain
amounts.

7. Click Save.
8. Optional: To consider additional factors in a decision, add more condition properties:
a. In the Conditions column, click a cell.
b. In the toolbar, click the Insert column after icon.
c. Define the condition property by repeating steps 3 through 7.
For example: Add more columns to evaluate the customer account type and the loan term, as shown
in the following figure:

Decision table with three columns

9. In the if row, click the cell under a property, and then enter a value that the decision table evaluates
at run time.
If you configure two or more conditions, enter a value for at least one of the conditions. Your
application ignores cells without values.
10. In the Return column, enter a return result. For example: You can configure a condition that if a
credit score is greater than 500, the return result is a loan interest rate of 3%.
11. Optional: To insert an additional value in a cell, add an OR condition:
To insert the OR condition before the current value, on the toolbar, click the Insert OR before
icon.
To insert the OR condition after the current value, on the toolbar, click the Insert OR after icon.
When an application evaluates the cell at run time, the application starts with the value in the top part
of the cell.
For example: The following figure shows a decision table that returns the rate interest for a loan. If a
customer's credit score is equal to or greater than 500, the customer account type is Standard or Gold,
the loan term is 12 months, and the rate interest is 3%.

Sample decision table

12. Optional: To provide more outcomes, populate more rows with values:
a. Click a cell in the if row.
b. In the toolbar, click the Insert row after icon.
c. Define the condition by repeating steps 3 through 10.
13. In the otherwise row, in the Return column, select or enter a property that defines an application
behavior when no condition in the table returns a true value. For example: Configure your
application to reject a case.
14. Optional: To ensure that your application can process the table, check the table for conflicts by
clicking Show conflicts on the toolbar. For example: If two rows are identical, the second row never
evaluates to true and is unreachable.Result: A warning icon appears in rows that are unreachable or
empty.
15. Optional: To increase the possibility of reaching a return value, improve the completeness of the
table by clicking Show completeness on the toolbar. Result: The system automatically adds
suggested rows to the decision table, that cover additional cases.
16. Click Save.
17. Optional: To import the decision table to an .xls file, for example to share with stakeholders offline, in
the toolbar, click Export.

Result: At run time, your application processes rows in the table starting from the top row and returns a
result for the row that is first to evaluate to true.For example: The following figure shows a decision table
that calculates the interest rate for a loan. The decision table evaluates rows that include values that define
the customer's credit score, account type, and loan term. The application returns the result of the first row
that evaluates to true. If all rows evaluate to false, the application returns the result that the interest rate is
10%.

Decision table to calculate interest rates

What to do next: Define additional options for the decision table. For example, decide whether an
application continues evaluating the table after one row evaluates to true. For more information, see
Configuring additional options for a decision table.

Decision tables
Viewing rule history
More about Decision Tables

Specifying pages and classes of a decision table rule

To ensure that a decision table accesses or updates information on clipboard pages, specify the page name
and class of the pages. At run time, these pages contain the properties that a decision table references on
other tabs of its rule form.

Define the pages and classes of a rule to:

Set up rule prompting during rule configuration.

Configure rule validation.
Apply default class for list elements.

For more information about pages and classes, see Defining the pages and classes of a rule.

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

2. Expand the Decision category, and then click Decision Table.
3. In the list of decision table instances, click the decision table that you want to edit.
4. On the rule form, click the Pages & Classes tab.
5. In the Page name field, enter the name of the page that contains the property that this rule
references.
6. In the Class field, select the class of the page.
7. Optional: To add more pages and classes, click Add item, and then repeat steps 5 and 6.
8. Click Save.

Creating decision tables

Configuring additional options for a decision table
Organizing rules into classes
Configuring additional options for a decision table
Adjust how your decision table works by configuring additional options. For example, you can configure how
a decision table behaves after one row evaluates to true, or define which elements of a decision table are
available for edits.

Consider a scenario in which a user with a managerial role needs to update the results that the decision
table returns. To avoid unintentional changes in the decision table, you can prevent users from
manipulating columns and rows, and allow for editing only the results.

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

2. Expand the Decision category, and then click Decision Table.
3. In the list of decision table instances, open the decision table that you want to edit.
4. On the Results tab, in the Delegation options section, configure the initial presentation and
available options for the decision table:
To continue processing after one row in the decision table evaluates to true, select the Evaluate
all rows check box.

At run time, when a decision table evaluates all rows, the application performs the results from all
rows that evaluate to true. If you leave this check box clear, the application performs the result
from the first row that evaluates to true.

To disable row manipulation in the decision table, for example by adding or removing rows, clear
the Allowed to update row layout check box.

Note: Users with rule-editing privileges can update the cell values within an individual row, even
if this check box is clear.

To disable column manipulation in the decision table, for example by adding or removing
columns, clear the Allowed to update column layout .

Note: Users with rule-editing privileges can update the cell values within an individual column
even if this check box is clear.

To prevent changes to the cell values, clear the Allowed to change property sets check box.
To prevent access to the Expression Builder from any cell of the decision table, select the
Allowed to build expressions.

Note: Users with rule-editing privileges can add constants or property references in a row or
column cell even if this check box is clear.

To hide the Result column of the decision table to indicate that the decision table does not return
an explicit value that represents the overall processing result, clear the Allowed to return
values check box.

If you select this check box, you can also restrict the list of possible return values. This check box
is available only when you leave the Evaluate all rows check box clear.

5. Optional: To specify allowed results for the decision table, in the Results section, in the Results
defined by property field, enter a property that lists the allowed results. For example: In an online
shopping application, you can select a property that lists countries to which the shop can send parcels,
such as only countries within the European Union.
6. Optional: To match the allowed results that you provided in step 5 with specific values, map the
results to properties:
a. Expand the Additional Allowed Results. When selected, each target property will be
assigned the value specified section.
b. In the Result field, enter a value that the decision table can return at run time.
c. In the Target property field, enter a property that the system updates after the decision table
returns the result that you specified in step 6.b.
d. In the Value field, enter a value to update the property that you specified in step 6.c.
e. Optional: To update more properties when the table returns a specific result, under the Target
property field, click Add item, and then repeat steps 6.c and 6.d.
f. Optional: To match more results with properties, under the Result field, click Add item, and
then repeat steps 6.b through 6.d.
For example: If the decision table returns countries within the European Union to which an online
 shop can send parcels, you can define different shipping costs for different countries. When the
decision table returns one of the countries as a result, the system automatically returns a property
that specifies the shipping costs for that country.
7. Optional: To set properties before the system starts processing the decision table, define properties
to precalculate:
a. Expand the Preset Properties section.
b. In the Property field, enter a property that you want to set before processing of the decision
table.
c. In the text field, provide a value for the property by entering a constant, property name,
expression, or input parameter.
d. To set more properties, click Add a row, and then repeat steps 7.b and 7.c.
For example: You can enter an expression that at run time automatically populates a property that
holds a current date.
8. Click Save.

Decision tables
Creating decision tables
Viewing rule history
More about Decision Tables

More about Decision Tables

Use a decision table to derive a value that has one of a few possible outcomes, where each outcome can
be detected by a test condition. A decision table lists two or more rows, each containing test conditions,
optional actions, and a result.

Uploading an Excel spreadsheet to start

If you have in advance a Microsoft Excel spreadsheet in XLS file format that contains useful starting
information for a decision table, you can incorporate (or "harvest") the XLS file and the information it
contains directly into the decision table.

This feature lets people with no access to the Pega Platform record their decision rules using a familiar
software program.

Evaluating a decision table

In an activity, to evaluate a decision table and derive a value, your application can:

Use the Property-Map-DecisionTable method

Call the standard function DecisionTable.ObtainValue()
Call the standard activity @baseclass.DecisionTableLookup

Method
In an activity, call the method Property-Map-DecisionTable method. As parameters, enter the target
property name and the name of the decision table.

Standard function
In an activity, call the standard function named DecisionTable.ObtainValue to evaluate a decision table. Use
the syntax:

Lib(Pega-RULES:DecisionTable).ObtainValue(this, myStepPage, "decisiontablename")

Performance
The Pega Platform does not limit the number of rows in a decision table. However, as a best practice to
avoid slow performance when updating the form and also avoid the Java 64KB code maximum, limit your
decision tables to no more than 300 to 500 rows.
Standard activity
The standard activity named @baseclass.DecisionTableLookup also evaluates a decision table. (This
approach is deprecated.)

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Special processing with Declare Expression calls

When a Declare Expression rule has Result of decision table for the Set Property To field, special processing
occurs at runtime when a property referenced in the decision table is not present on the clipboard.
Ordinarily such decision rules fail with an error message; in this case the Otherwise value is returned
instead. For details, see the Pega Community article Troubleshooting: Declarative Expression does not
execute when a decision rule provides no return value.

Not declarative
Despite the class name, the Rule-Declare-DecisionTable rule type does not produce forward or backward
chaining. Technically, it is not a declarative rule type.

Decision tables
Creating decision tables
Viewing rule history

About Decision Trees

Use a decision tree to record if .. then logic that calculates a value from a set of test conditions organized as a
tree structure on the Decision tab, with the 'base' of the tree at the left.

The following tabs are available on this form:

Decision
Input
Results
Test Cases

Where referenced
Rules of four other types can reference decision trees:

In a flow rule, you can reference a decision tree in a decision shape, identified by the Decision shape
.
In an activity, you can evaluate a decision tree using the Property-Map-DecisionTree method.
A Declare Expression rule can call a decision tree.
A collection rule can call a decision table.

Access
Use the Application Explorer to access decision trees that apply to work types in your current work pool.
Use the Records Explorer to list all decision trees available to you.

Development
The Decision tab offers various formats and choices, depending on settings on the Results tab:

For an advanced decision tree, complete the Input tab before the Decision tab.
For a basic decision tree, complete the Results tab first. To restrict the results to one of a few constant
values, complete the Results tab before the Decision tab.

After you complete initial development and testing, you can delegate selected rules to line managers or
other non-developers. Consider which business changes might require rule updates and if delegation to a
user or group of users is appropriate. For more details, see Delegating a rule or data type.

Category
Decision tree rules are instances of the Rule-Declare-DecisionTree class. They are part of the Decision
category.

Creating decision trees

Calculate a value from a set of properties or conditions where true comparisons can lead to additional
comparisons, organized and displayed as a tree structure, by creating a decision tree. For example,
you can create a condition that checks whether the location of a job candidate is equal to a specific
city. If the condition is true, your application evaluates additional conditions, such as work experience
and education.

Completing the Decision tab (Advanced format)

Record the if.. then.. logic of the decision tree in the three-column array. These unlabeled columns are
known as the comparison, action, and next value columns.

Completing the Decision tab (Basic format)

Record the if.. then.. logic of the decision tree in this array, which has three columns. The unlabeled
columns are known as the comparison, action, and next value columns.

Completing the Pages & Classes tab

The system uses this tab to locate properties on the clipboard.

Completing the Configuration tab

Complete the fields on this tab to restrict the possible values returned by this decision tree. Additional
options allow you to control the actions that other users can take on the Decision tab.

More about Decision Trees

Configuring rows and columns in a map value

Complete the fields in the Input Rows and Input Columns sections of the Configuration tab to guides
your inputs on the Matrix tab of a map value.

Viewing rule history

Creating decision trees

Calculate a value from a set of properties or conditions where true comparisons can lead to additional
comparisons, organized and displayed as a tree structure, by creating a decision tree. For example, you
can create a condition that checks whether the location of a job candidate is equal to a specific city. If the
condition is true, your application evaluates additional conditions, such as work experience and education.

1. In the header of Dev Studio, click Create Decision Decision Tree .

2. In the Label field, enter a name that describes the purpose of the decision tree.
3. In the Apply to field, select the class in which you want to create the decision tree.
4. Click Create and open .
5. Select the branch to display the columns.
6. Define a condition and a result:
Choices Actions

a. In the first field, enter a property or a value.

b. In the drop-down list, select a comparator.
c. In the next field, enter a property or value that your application compares against
Define a the first property or value.
single d. In the then list, select return.
condition e. In the last field, enter a property or value result that you want your application to
return. For example: If you want a reporting manager to review any job
 Choices application from candidates withActions
> than 10 years of work experience, you can
create the following condition and result: if .WorkExperience > 10 then return Work Manager.

a. In the first field, enter a property or a value.

b. In the drop-down list, select a comparator.
c. In the next field, enter a property or value that your application compares against
Define the first property or value.
nested d. In the then list, select continue.
conditions e. Select the next branch to display the columns.
f. Define a nested condition by providing a property or value, a comparator, and a
result. For example: If the work experience of a job candidate is greater than 10
years, then your application checks whether the candidate has a master's degree.
7. Optional: To create complex conditions, click Add row, and then repeat step 6.
8. In the otherwise section, define the behavior of your application if all of the conditions evaluate as
false:
Choices Actions

a. From the list, select Return.

b. In the Default return value field, enter a value that
you want to use.
c. Optional: To configure your application to perform an
Return a value
action, click Take actions, click Add a row, and then
define the action. For example: Change a case status
by defining the following action: Set pyUpdateCaseStatus equal
to Resolved-Rejected.

a. From the list, select Take action.

Perform an actionNote: In order to b. Click Actions.
select this option, on the c. Click Add a row.
Configuration tab, select the Allow d. Define an action by setting a value for the action
selection of additional return property. For example: Change a case status by
actions check box. defining the following action: Set pyUpdateCaseStatus equal to
Resolved-Rejected.

9. Optional: To ensure that your application can process the tree, check the tree for conflicts by clicking
Show conflicts on the toolbar. For example: If one row checks whether the work experience is
greater than 5 years, and the second row checks whether the work experience is greater than 3 years,
the second row never evaluates to true because the first row includes the second row
condition.Result: A warning icon appears in rows that are unreachable or empty.
10. Optional: To increase the possibility of reaching a return value, test for completeness of the tree by
clicking Show completeness on the toolbar. Result: The system automatically adds suggested rows
of the decision tree that cover additional cases.
11. Click Save.

About Decision Trees

Viewing rule history
More about Decision Trees

Completing the Decision tab (Advanced format)

Record the if.. then.. logic of the decision tree in the three-column array. These unlabeled columns are known
as the comparison, action, and next value columns.

This help topic describes the advanced format of the Decision tab. If you encounter a Decision tab that
does not contain an Evaluate Parameter or Evaluate property name see Completing the Decision tab (Basic
format).

At run time, the system evaluates the if portion of the array, starting at the top row, and continues until it
reaches a Return statement. If the system processes the entire tree but does not reach a Return statement, it
returns the Otherwise value.

The Evaluate field at the topic identifies the Property value, if any, from the Configuration tab. When this
field is blank, the value is taken from a parameter of the Property-Map-DecisionTree method. If this decision
tree was created in basic mode or if the Allowed to Evaluate Properties? box on the Configuration tab
is not selected, the Evaluate field does not appear

If the Redirect this Rule? check box on the Configuration tab is selected, this circumstance-qualified
rule is redirected and tab is blank.

Understanding the branch structure

Each indent level supports comparisons against a single value, which are determined by context:

The top (leftmost) level tests values against the value of the property that is identified on the
Configuration tab, or a parameter value specified in the method that calls the decision tree.
Comparisons are implicit: the property on the Configuration tab (or the parameter in the method) is
not displayed on this tab.
An indented level tests values against a property identified in the Evaluate field of the statement
above the indented level.
Each text box can contain a value, a comparison operator followed by a value, or a Boolean
expression. The context is not relevant when a Boolean expression is evaluated.

Using the controls

To display controls for that row or field, click it.

Control Action

Click to hide subtree structures, or to hide specific subtree structures, click the minus
Collapse All
sign.

Click to show all the subtree structures, or to display specific subtrees, click the plus
Expand All
sign.

Open
Click to start the Expression Builder. This tool provides prompting and guidance when
expression
you create complex expressions involving functions. See Using the Expression Builder.
builder icon

Open icon Click to review a property for a field that contains a property reference.

Add row
Click to select a row. Then click the appropriate buttons to insert, append, or delete a
and Delete
row, respectively.
row buttons

Click to analyze the consistency of the tree. This button displays a Warning icon next
to any parts of the tree that are unreachable. For example, a branch that extends below
the two mutually contradictory tests (if Width > 100) and (if Width < 100) is
unreachable.

To highlight the parts of the tree that cause that branch to be unreachable, click the
Warning icon. A decision tree that contains no unreachable parts is called consistent.

Show The presence of unreachable portions of the tree does not prevent you from saving the
Conflicts rule. Comparisons involving two properties such as Width > Length are ignored in this
analysis.

Conflicts are also checked when you save the form, and when you use the Guardrails
landing page for the application.

Conflicts do not prevent the rule from being validated or executed, but could indicate
that a rule does not work as intended.

Click to automatically add suggested portions of the decision tree that cover additional
cases and reduce or eliminate the situations that fall through to the Otherwise Return
Show
expression. Suggested additions are displayed with a light green highlight and can refer
Completeness
to values that you must modify such as Result or DecisionTreeInputParam. These
additions are only suggestions; you can alter or delete them.
Modifying branches with drag and drop operations
To move a subtree structure, drag the small circle at its left.

To copy a subtree structure, drag while holding down the CTRL key, and drop it on the destination node.

Completing fields in a branch

Field Description

Enter a value for the current context, or a comparison starting with one of the six comparison
operators: <, >, =, !=, >= or <=.

The value can be an expression, such as a literal value between quotations or a Single Value
if / if property reference. (For more information, see About expressions.) To select a pattern that
value is helps you enter Boolean expressions, click the drop-down button. The form changes to reflect
your pattern decision.

If the Action field is set to Otherwise, this field is not visible .

Select an action from the selection list. The action that you choose determines which branch
of this decision tree the system follows at run time when the condition to its left is reached
and evaluates to true. Select a keyword:

Return
Causes this branch of the decision tree to end processing when reached. If the system
finds a Return row to be true, the value in the right column of this row becomes the
result of the decision tree evaluation.
Continue
Causes the next row of the decision tree to be nested within this branch. The system
reflects the nesting by indenting the next row on the form display and changing the right
arrow to down arrow so that it points down to the indented row. The context for the
Continue statement is the same as for the current statement.

Evaluate

Causes the system to use a new property, identified in the right column, as the context
for nested comparisons below the current row. Enter a Single Value property reference in
the Value field to the right of the Action field.

This choice is not available for decision trees that are created in basic mode, or when the
Allowed to Evaluate Properties check box on the Configuration tab is not selected.

Call Decision Tree

Causes the system to evaluate another decision tree, which is identified in the field to
the right of this value. The result of the second decision tree becomes the result of this
decision tree, and evaluation ends.

At run time, if this decision table evaluates in a backward-chaining context (the

AllowMissingProperties parameter to the method is true ), the system evaluates the called
(action) decision tree in the same way.

This choice is not available for decision trees that are created in basic mode, or when the
Allowed to Call Decision check box on the Configuration tab is not selected.

Call Map Value

Causes the system to evaluate a map value, identified in the next field. The result of the
map value becomes the result of this decision tree, and evaluation ends.

At run time, if this decision table evaluates in a backward-chaining context (the

AllowMissingProperties parameter to the method is true), the system evaluates the
called map value in the same way.
Field This choice is not available for decision trees that are created in basic mode, or when the
Description
Allowed to Call Decision check box on the Configuration tab is not selected.

Call Decision Table

Causes the system to evaluate a decision table, identified in the next field. The result of
the decision table becomes the result of this decision tree, and evaluation ends.

At run time, if this decision table evaluates in a backward-chaining context (the

AllowMissingProperties parameter to the method is true), the system evaluates the
called map value in the same way.

This choice is not available for decision trees that are created in basic mode, or when the
Allowed to Call Decision check box on the Configuration tab is not selected.

Otherwise
Select Otherwise only as the final choice in a set of alternatives. The value in the right
column of this bottom row becomes the result of this decision tree evaluation.

Identify a target based on the action value.

If you selected Return as the action and the Configuration tab is not blank, select one of the
values listed on the Configuration tab.

Otherwise, enter a value or expression here that allows evaluation of the decision tree to
continue. You can reference a property on any page, but be sure to enter any page you
reference on the Pages & Classes tab. Enter a value that depends on the one of the
following action value keywords:

Return or Otherwise
Enter an expression for the result of this decision tree when this row is the final one
evaluated.
Evaluate
Identify a property reference that the system uses at run time to evaluate the nested
comparisons beneath the row that contains the Evaluate action. This option is not available
for decision trees that are created in basic mode, or when the Allowed to Evaluate
Properties check box on the Configuration tab is not selected.
right Call Decision Tree
arrow Select another decision tree. The result of that rule becomes the result of this rule.
(next Call Map Value
value) Select a map value. The result of that rule becomes the result of this rule.
Call Decision Table
Select a decision table. The result of that rule becomes the result of this rule.
Call Base Decision Tree
Available only for decision trees that are circumstance-qualified. When selected, the
base (or non-qualified) decision tree of the same name, ruleset, and version is executed.
Take Action
Set one or more properties to values as the only outcome of the decision tree. This ends
evaluation of the rule, returning the null string as its result. This capability is not
available for decision trees that are created in basic mode, or when the Allowed to
Take Action check box on the Configuration tab is not selected.

This input field is not displayed when the action value is Continue.

To open a referenced decision tree, map value, or decision table, Click the Open icon. (The
Call Decision Tree , Call Map Value,
and Call Decision Table choices are not available for decision trees that
are created in basic mode, or when the Allowed to Call Decisions? field on the
Configuration tab is not selected.)

Click to access an optional array of properties and values. To hide this array, click .

When the system evaluates the decision tree at run time and this row is the source of the
results, the system also recomputes the value of the target properties that are identified in
this array. Order is significant.
 Field This capability is not available for decision trees that are created in basic mode, or for
Description
decision trees when the Allowed to Set Take Action? check box on the Configuration tab
is not selected.

Property Optional. Identify a property reference corresponding to a value to be set.

Value Enter a value for that property — a constant, property reference, or expression.

Completing the Otherwise branch

Field Description

Otherwise

To define the outcome of this decision tree when no result is determined by the tree
structure above, choose Return or Take Action. If this field is blank and no other return value is
computed, the system returns the null value.

Return

Choose Return to specify a value to return if an earlier branch does not return a value.

If the Allowed Results list on the Configuration tab is not blank, this field is required
and is limited to one of the constant values that are listed on that tab.

For guided assistance in entering an expression start the Expression Builder by clicking
the Open expression builder icon.

Return Note: During backward chaining computations for Declare Expression rules, if the
Otherwise Return value can be computed, but properties that are needed for other
parts of the form are not defined, the Otherwise Return value is returned as the value
of the decision table.
Take Action

Choose Take Action (when this choice is visible) to return the empty string as the value of
the decision tree, but to also evaluate a function that is identified by an alias in the
Allowed Action Functions field of the Configuration tab.

Most commonly, the Take Action choice allows one or more property values to be set as
the outcome of a decision tree.

Select a property in the Set field. Enter a value for the property in the Equal to field.

About Decision Trees

Creating decision trees
Viewing rule history
More about Decision Trees

Completing the Decision tab (Basic format)

Record the if.. then.. logic of the decision tree in this array, which has three columns. The unlabeled columns
are known as the comparison, action, and next value columns.

This help topic describes the basic format of the Decision tab. If you encounter a Decision tab that
contains an Evaluate Parameter or Evaluate property name, see Completing the Decision tab (Advanced
format).

At run time, the system evaluates the if portion of the array, starting at the top row, and continues as
described here until it reaches a Return statement. If the system processes all rows but does not reach a
Return statement, it returns the Otherwise value.

If the Redirect this Rule? check box on the Results tab is selected, this circumstance-qualified rule is
redirected and this tab is blank.

Understanding the rows

Each text box can contain a value, a comparison operation for two values, followed by an outcome. The
comparison can be between two properties or between a property and a constant value.

To make controls for a row or field visible, click that field :

To hide subtree structures, click Collapse All. To hide specific subtree structures, click the minus
sign.
To show all subtree structures, click Expand All. To display specific subtrees, click the plus sign
To review a property for a field that contains a property reference, click the Open icon.
To append or delete a row, select a row and then click the Add or Delete icon, respectively.

Field Description

Enter a comparison by using one of the six comparison operators: <, >, =, !=, >= or <=.
if / if
The value can be a constant or a Single Value property reference.
value is
If the Action field is set to Otherwise, this field is not visible.

Select an action from the selection list. The action that you choose determines which branch
of this decision tree the system follows at run time when the condition to its left is reached
and evaluates to true. Select a keyword:

Return
Causes this branch of the decision tree to end processing when reached. If the system
finds a Return row to be true, the value in the right column of this row becomes the
result of the decision tree evaluation.
Continue
Causes the next row of the decision tree to be nested within this branch. The system
reflects the nesting by indenting the next row on the form display and changing the
right arrow to down arrow to point down to that indented row. The context for the
continue statement is the same as for the current statement.
Call Decision Tree

Causes the system to evaluate another decision tree, identified in the next field.

This choice might not be present in all cases, depending on settings on the Results
tab.

At run time, if this decision table evaluates in a backward-chaining context (the

AllowMissingProperties parameter to the method is true), the system evaluates the
called decision tree in the same way.

Call Map Value

(action)
Causes the system to evaluate a map value, identified in the next field.

This choice might not be present in all cases, depending on settings on the Results
tab.

At run time, if this decision table evaluates in a backward-chaining context (the

AllowMissingProperties parameter to the method is true), the system evaluates the
called map value in the same way.

Call Decision Table

Causes the system to evaluate a decision table, identified in the next field.

This choice might not be present in all cases, depending on settings on the Results
tab.

At run time, if this decision table evaluates in a backward-chaining context (the

 Field AllowMissingProperties parameterDescription
to the method is true), the system evaluates the
called decision table in the same way.

Otherwise
Select Otherwise only as the bottom, final choice in a set of alternatives, marking the final
choice. The value in the right column of this row becomes the result of this decision
tree evaluation.

Identify a target based on the action value.

If you selected Return as the action and the Results tab is not blank, select one of the values
listed on the Results tab.

Otherwise, enter a value or expression here that allows the evaluation of the decision tree
to continue. You can reference a property on any page, but be sure to enter any page you
reference on the Pages & Classes tab. Enter a value that depends on the action value
keyword:

Return or Otherwise — Enter an expression for the result of this decision tree when this row
is the final one evaluated.
(next Call Decision Tree — Select another decision tree. The result of that rule becomes the result
value) of this rule. This choice might not be present in all cases, depending on settings on the
Results tab.
Call Map Value — Select a map value. The result of that rule becomes the result of this
rule. This choice might not be present in all cases, depending on settings on the
Results tab.
Call Decision Table — Select a decision table. The result of that rule becomes the result of
this rule. This choice might not be present in all cases, depending on settings on the
Results tab.

This input field is not displayed when the action value is Continue.

To open a referenced decision tree, map value, or decision table, click the Open icon.

Click to access an optional array of properties and values. To hide this array, click the
Collapse icon . This choice might not be present in all cases, depending on settings on the
Results tab.
Expand
icon When the decision tree evaluates and this row is the source of the results, the system also
recomputes the value of the target properties that are identified in this array. Order is
significant.

Property Optional. Identify a property reference to be set.

Value Enter a value for that property.

Otherwise

Optional. Enter an expression defining a value to return when the decision tree evaluation
does not return another value. When the Allowed Results list on the Results tab is not
blank, this field is required and limited to one of the constant values listed on that tab.
Return
If this field is blank and no other return value is computed, the system returns the null
value.

Completing the Configuration tab

About Decision Trees
Creating decision trees
Viewing rule history
More about Decision Trees

Completing the Pages & Classes tab

The system uses this tab to locate properties on the clipboard.

The system completes a row from the Applies To key part of this decision tree. If your decision tree does
not reference any properties other than those in the Applies To class, you do not need to add other rows
this array.

See How to Complete a Pages & Classes tab for basic instructions.

Field Description

Optional. Enter the name of the clipboard page on which the property or properties are to be
found at runtime.

Optionally, add a row with the keyword Top as the page name, to identify a top-level page. The
Page Top keyword allows you to use the syntax Top.propertyref to identify properties, on other tabs of
Name this rule form.

Decision tree rules can apply to embedded pages that appear within top-level pages with various
names. In such cases, you can use the keywords Top or Parent in the page name here.

Class Optional. Select the class of that page.

About Decision Trees

About Decision Trees

Creating decision trees
Viewing rule history
More about Decision Trees

Completing the Configuration tab

Complete the fields on this tab to restrict the possible values returned by this decision tree. Additional
options allow you to control the actions that other users can take on the Decision tab.

Options
The fields in this section impact the initial presentation and available options on the Decision tab of the
decision tree.

For example, you can prevent users from calling specific function aliases or adding new nodes to the tree
structure. This helps you customize the development experience for delegated users, such as line
managers, who may not require access to the full set of decision tree options.

All users, including delegated users, can remove these restrictions if they hold a rule editing privilege.

Field Description

Select this check box to allows users to change the function aliases called by each
tree node on the Decision tab.

Clear this check box to hide the function alias picker on the Decision tab. Users
with rule editing privileges can still update the constant values in each tree node.

With this option selected you can:

Populate the Functions Allowed list to restrict the function aliases a user can
Allow changes to select.
function lists
Function aliases commonly used by managers include: CompareTwoValues,
allEntriesSatisfyCondition, and anyEntrySatisfiesCondition .

Leave the Functions Allowed list empty to let users select any available
function alias.
 Field Open any functionDescription
alias in the Functions Allowed list.

Select this check box to allow users to append and insert top-level tree nodes on
Allow adding of the Decision tab.
nodes to the
decision tree Clear this check box to hide the add icon on the Decision tab.

Select this check box to allow users to evaluate the value of a property from a
tree node on the Decisiontab.

Allow selection of Clear this check box to hide the evaluate option from then drop-down list on the
'evaluate property' Decision tab.
option
You must have the Allow adding of nodes to the decision tree option
selected before you can change the state of this check box.

Select this check box to allow users to call a map value, decision tree, or decision
table from a tree node on the Decision tab.

Allow selection of Clear this check box to hide decision rules from the list of available options in the
'call decision' then statement of the Decision tab.
option
You must select the Allow adding of nodes to the decision tree option before
you can change the state of this check box.

Select this check box to make the Take Action option visible on the Decision tab.
Users can take action within each tree node or as part of the otherwise
statement on the Decision tab.

With this option selected, you can:

Allow selection of Populate the Allowed Action Functions list to restrict the function aliases a
additional return user can call from an action.
actions
The setPropertyValue function alias is commonly used by managers.

Leave the Allowed Action Functions list empty to let users call any
available function alias.

Open any function alias in the Allowed Action Functions list.

Results
Use the options in this section of the tab to define the possible values this decision tree can return. You can
also specify a list of preset properties that are calculated before the decision tree runs.

To define allowed results:

1. Enter a property or linked property name in the Results defined by property field.

This property must use table validation because the table values are used to populate the Result
field.

2. Select a value from the Result list.

Alternatively, you can enter a string value without quotes to supplement the existing values from the
property that uses table validation.

3. Define a list of Target Property and Value pairs that are set when the decision tree returns the
corresponding Result.
 You can enter a constant, property name, or expression in the Value fields.

4. Repeat steps 2 and 3 as necessary.

At run time, the system sets target properties using the order you specify.

To define preset properties:

1. Enter a property name in the Property field.

2. Enter a constant, property name, expression, or input parameter in the Value field.

3. Click the add icon and repeat this process for as many properties as are required.

These properties are set before the Decision tab is processed.

About Decision Trees

Creating decision trees
Viewing rule history
More about Decision Trees

More about Decision Trees

Overriding the property
Decision tree evaluation may be based on a known property identified on the Configuration tab, or on a
parameter supplied in the Property-Map-DecisionTree method, or both.

If you leave the Property field blank, evaluation is always based on the parameter. If a parameter is
supplied, the parameter value is used even when the Property field is not blank.

Standard functions
As an alternative to the Property-Map-DecisionTree method, you can use these standard functions to
evaluate a decision tree:

@(Pega-RULES:DecisionTree).ObtainValue(tools, myStepPage, decisiontree, inputproperty)

@(Pega-RULES:DecisionTree).ObtainValue(tools, myStepPage, decisiontree, inputproperty, bAllowMissingProperties)

Decision tree rules can also be evaluated as part of a collection rule ( Rule-Declare-Collection rule type).

Pega Community note

See the Pega Community article How to evaluate a decision tree and handle errors for an example.

Uploading a text file to start

You can create a decision tree by importing (or "harvesting) a specially formatted text file. This capability
lets others not familiar with the Pega Platform create decision trees.

Performance
The number of nodes in a decision tree is not limited. However, as a best practice to avoid slow
performance when updating the form and also avoid the Java 64 KB code maximum, limit your decision
trees to no more than 300 to 500 rows.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Special processing with Declare Expression calls

When a Declare Expression rule has Result of decision tree for the Set Property To field, special processing occurs
at runtime when a property referenced in the decision table is not present on the clipboard. Ordinarily such
decision rules fail with an error message; in this case the Otherwise value is returned instead. For details,
see the Pega Community article Troubleshooting: Declarative Expression does not execute when a decision
rule provides no return value.

Not declarative
Despite the class name, the Rule-Declare-DecisionTable rule type does not produce forward or backward
chaining. Technically, it is not a declarative rule type.

Custom function aliases

You can use Configuration tab to enable custom function aliases instead of the default comparison. For
some of those aliases, you can click Select values and select from a list of values that are available for the
selected property.

Application debugging using the Tracer tool

About Decision Trees
Creating decision trees
Viewing rule history

Configuring property evaluation in a decision tree

The run-time result of a decision tree can depend on the value of a property or the optional, third
parameter of the Property-Map-DecisionTree method.

The following fields are visible when the Allow selection of 'evaluate property' option check box on
the Configuration tab is selected. Use them to configure the property used by evaluate nodes in the
decision tree.

Field Description

Choose String, Number, or Boolean to specify how the system evaluates the comparisons defined
on the Decision tab when an optional parameter value is supplied in the Property-Map-
DecisionTree method.

The Data Type value you select affects comparisons on the Decision tab when the system
obtains the input value as a method parameter.

For example, if the method parameter is "007" and the Data Type is String, then a comparison
Data of "007" < "7" is true. If the method parameter is "007" and the Data Type is Number, then the
Type comparison of "007" < "7" is false.

The Data Type is ignored when the property identified in the next field is used at runtime. In
that case, comparisons depend on the type of that property.

This Data Type is independent of — and need not match — the type of the property to contain
the decision tree result (the first parameter to the Property-Map-DecisionTree method). For
example, you can evaluate comparisons of inputs based on numbers and return a result
property of type Text.

Optional. Enter a Single Value property reference, or a literal value between double quotes. (If
your property reference doesn't identify a class, the system uses the Applies To portion of the
key to this decision tree as the class of the property).
Property
At runtime, if the value of the third parameter to the Property-Map-DecisionTree method is
blank, the system uses the value of this property for comparisons.

Optional. Enter a text label for the input property. This label appears on the Decision tab.
Label
Choose a meaningful label, as certain users may see and update only the Decision tab.
About Decision Trees

About Decision Trees

Creating decision trees
Viewing rule history
More about Decision Trees

About Map Values

Use a map value to create a table of number, text, or date ranges that converts one or two input values,
such as latitude and longitude numbers, into a calculated result value, such as a city name. Map value rules
greatly simplify decisions based on ranges of one or two inputs. Use a map value to record decisions based
on one or two ranges of an input value. A map value uses a one- or two-dimensional table to derive a
result.

Through cascading — where one map value calls another — map values can provide an output value based
on three, four, or more inputs.

Complete the Configuration tab before the Matrix tab.

Where referenced

Rules of five types can reference map values:

In a flow, you can reference a map value in a decision task, identified by the Decision shape in a flow.
In an activity, you can evaluate a map value using the Property-Map-Value method or Property-Map-
ValuePair method.
A Declare Expression rule can call a map value.
A map value can call another map value.
A collection rule can call a map value.

Access

Use the Application Explorer to access the map values that apply to work types in your application. Use the
Records Explorer to list all the map values available to you.

After you complete initial development and testing, you can delegate selected rules to line managers or
other non-developers. Consider which business changes might require rule updates and if delegation to a
user or group of users is appropriate. For more details, see Delegating a rule or data type.

Category

Map values are part of the Decision category. A map value is an instance of the Rule-Obj-MapValue rule
type.

Map Values
Completing the Matrix tab

Map Value form - Completing the Matrix tab

Completing the Configuration tab

Complete the fields on this tab to guide your inputs on the Matrix tab and define the possible values
returned by this map value.

Completing the Pages & Classes tab

Identify what is known about the class of each page that is referenced on other tabs. See How to
Complete a Pages & Classes tab for basic instructions.

More about Map Values

Map value rules can be updated as needed to reflect changing business conditions, without the need
to ask a skilled developer to modify complex activities or other rules.

Configuring property evaluation in a decision tree

 The run-time result of a decision tree can depend on the value of a property or the optional, third
parameter of the Property-Map-DecisionTree method.

Unit testing a map value

You can test a map value individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Map Values
Records can be created in various ways. You can add a new record to your application or copy an existing
one. You can specialize existing rules by creating a copy in a specific ruleset, against a different class or (in
some cases) with a set of circumstance definitions. You can copy data instances but they do not support
specialization because they are not versioned.

Create a map value by selecting Map Value from the Decision category.

Key parts:

A map value has two key parts:

Field Description

Select a class that this map value applies to.

The list of available class names depends on the ruleset that you select. Each class can
restrict applying rules to an explicit set of rulesets as specified on the Advanced tab of the
class form.
Apply to
Map value rules can apply to an embedded page. On the Map Value form, you can use the
keywords Top and Parent in property references to navigate to pages above and outside the
embedded page. If you use these keywords, include the class and absolute name — or a
symbolic name using Top or Parent — on the Pages & Classes tab.

Enter a name that is a valid Java identifier. Begin the name with a letter and use only letters,
Identifier
numbers, and hyphens. See How to enter a Java identifier.

Rule resolution

When searching for instances of this rule type, the system uses full rule resolution which:

Filters candidate rules based on a requestor's ruleset list of rulesets and versions
Searches through ancestor classes in the class hierarchy for candidates when no matching rule is
found in the starting class
Finds circumstance-qualified rules that override base rules
Finds time-qualified rules that override base rules

About Map Values

Completing the Matrix tab

Map Value form - Completing the Matrix tab

This tab contains a table of one column (for a one-dimensional map value) or two or more columns (for a
two-dimensional map value). The order of rows and columns is important. Rows are evaluated from left to
right, and columns from top to bottom.

Complete the Configuration tab before updating the Matrix tab. Labels that you enter on the Configuration
tab appear on the Matrix tab to guide your input.

To limit possible results to values in a fixed list of constant values, complete the Configuration tab before
the Matrix tab.

Adding rows and columns

You can add new rows and columns by clicking Configure rows and Configure columns , respectively. You
can also perform these actions from the Configuration tab.

Assessing completeness and consistency

Optionally, you can use these buttons to determine whether the map value is complete and consistent
(based on a static evaluation).

Button Results

Mark with a warning icon any cells of the matrix that are unreachable. For example, if
two rows are identical, the second row can never evaluate to true and so cannot affect
the outcome of the rule.

Click the warning icon on a row to highlight with an orange background the other cells
that cause a cell to be unreachable. The selected row is highlighted with a yellow
background.
Show
Conflicts A map value that contains no such unreachable rows is called consistent.

Conflicts are also checked when you save the form, and when you use the Guardrails
landing page to run the guardrails check for the application.

Conflicts do not prevent the rule from validating or executing, but may indicate that the
rule does not implement the intended decision.

After you export a map value, you can make changes in the .xlxs file and import the
updated file. The map value rule form is updated with the changes you made.

You must import the same file that you exported. You can change the name of the
exported file and import the renamed file. However, you cannot import a file different
from the one you exported.
Import
The Default row and first rows are locked in the exported file. You cannot delete these
rows, and you cannot insert rows when you select these rows.

The Default column is locked in the exported file. You cannot delete this column, and
you cannot insert columns when you select this column.

Exports the map value in .xlxs format. After you make your changes and save this file,
Export
you can import it with your changes.

Automatically add suggested rows that cover additional cases and reduce or eliminate
Show
the situations that fall through to the Default row . Suggested additions appear with a
Completeness
light green background. They are only suggestions; you can alter or eliminate them.

Entering row and column header

Each row and column has a header that defines both a label and a comparison. To create, review or update
a row or column header:

1. Click Configure rows or Configure columns. A pop-up window appears.

2. Select a comparison operator: < > =, >=, <= or is missing. (If you omit an operator, the system assumes =.)
Select is missing to detect that a property is not present — not that it is present but has the null value.
3. Enter an expression. For each expression, you can enter a literal value, a property reference or a more
complex expression, including function calls.

The keyword Default always evaluates to true and appears as the final choice at the end of each row and
column. You can complete values for the Default row or leave them blank.

Completing a cell

If you completed a list of literal constant values on the Configuration tab, select one of those values for
each cell.

Otherwise, enter an expression in the cell — a constant, a property reference, a function call, or other
expression. For guidance while entering expressions, click the Expression Builder to start the
Expression Builder. (You can enter complex expressions and use the Expression Builder only if the Allowed
to Build Expressions? check box is selected on the Configuration tab.)

If a cell is blank but is selected by the runtime evaluation, the system returns the null value as the value of
the map value.

Cascading map values with Call

One map value cell can reference another map value as the source of its value. Type the word call followed
by the name (the second key part) of another map value with the same first key part. SmartPrompt is
available. Click the Open icon to open the other map value.

If, at run time, this map value executes in a backward-chaining mode (that is, the AllowMissingProperties
parameter of the Property-Map-Value method is True ), the called map value also executes in this mode.

About Map Values

Building expressions with the Expression Builder

Completing the Configuration tab

Complete the fields on this tab to guide your inputs on the Matrix tab and define the possible values
returned by this map value.

Security

The following options impact the initial presentation and available options on the Matrix tab.

For example, you can prevent users from accessing the Expression Builder or modifying the column layout
of the map value. This helps you customize the development experience for delegated users, such as line
managers, who may not require access to the full set of decision table options.

Note: All users with a rule-editing privilege, including delegated users, can remove these restrictions.
Field Description

Select this check box to allow users to modify the rows and columns of the
Matrix tab.
Allow updating of the
matrix configuration in Clear this check box to prevent users from updating row or column
delegated rules configuration. Users with rule-editing privileges can still change values
within the cells of the Matrix tab.

Select this check box to allow access to the Expression Builder from any
cell on the Matrix tab.
Allow use of the
expression builder on the Clear this check box to hide the Expression Builder icon. Users with rule-
matrix view editing privileges can still add constants or property references in a row
or column cell.

Input Rows

See Configuring rows and columns in a map value.

Input Columns

See Configuring rows and columns in a map value.

Results

Use the options in this section of the tab to define the possible values that this map value can return. You
can also specify a list of preset properties that are calculated before the map value runs.
To define allowed results:

1. Enter a property or linked property name in the Results defined by property field.

This property must use table validation because the table values are used to populate the Result
field.

2. Select a value from the Result list.

Alternatively, you can enter a string value without quotes to supplement the existing table values.

3. Define a list of Target Property and Value pairs that are set when the map value returns the
corresponding Result.

You can enter a constant, property name, or expression in the Value fields.

4. Repeat steps 2 and 3 as necessary.

At run time, the system sets target properties using the order you specify.

To define preset properties:

1. Enter a property name in the Property field.

2. Enter a constant, property name, expression, or input parameter in the Value field.

3. Click the add icon and repeat this process for as many properties as are required.

These properties are set before the rows and columns on the Matrix tab are processed.

About Map Values

Completing the Pages & Classes tab

Identify what is known about the class of each page that is referenced on other tabs. See How to Complete
a Pages & Classes tab for basic instructions.

Field Description

Optional. Enter the name of a clipboard page referenced on the Matrix or Configuration tab.

Optionally, add a row with the keyword Top as the page name, to identify a top-level page. The
Page Top keyword allows you to use the syntax Top.propertyref on other tabs of this rule form to
Name identify properties.

Map value rules can apply to embedded pages that appear within top-level pages with various
names. In such cases, you can use the keywords Top or Parent in the page name here.

Class Optional. Select the class of that page.

About Map Values

More about Map Values

Map value rules can be updated as needed to reflect changing business conditions, without the need to ask
a skilled developer to modify complex activities or other rules.

Uploading an Excel spreadsheet to start

If you have in advance an Excel spreadsheet in XLS file format that contains useful starting information for
a map value, you can incorporate (or "harvest") the XLS file and the information it contains directly into the
new rule.

Evaluating
Both rows and columns contain a Type field (set on the Headers tab). The system makes comparisons
according to the data type you recorded on the Headers tab, converting both the input and the conditions
to the specified data type.

At runtime, the system evaluates row conditions first from top to bottom, until one is found to be true. It
then evaluates column conditions for that row, left to right, until one is found to be true. It returns the value
computed from that matrix cell.

Where map values are used

You can reference map values in the following places:

In activities that use the Property-Map-Value method or the Property-Map-ValuePair method. These
methods evaluate a one-dimensional or two-dimensional map value, compute the result, and store the
result as a value for a property.
In other map values, through a Call keyword in a cell.
Through a standard function ObtainValuePair() in the Pega-RULES:Map library.
On the Rules tab of a collection.

Input parameters in called map values rules

If a map value is evaluated through a decision shape on a flow, or one of the two methods noted above, the
input value or values may be literal constants or may be property references, recorded in the flow or in the
method parameters.

However, if a map value is evaluated by a Call from a cell in another map value, the evaluation always
uses the Input Property on the Header tab. Nothing in the Call can override this source.

Special processing with Declare Expression calls

When a Declare Expression rule has Result of map value for the Set Property To field, special processing occurs
at runtime when a property referenced in the decision table is not present on the clipboard. Ordinarily such
decision rules fail with an error message; in this case the Default value is returned instead. For details, see
the Pega Community article Troubleshooting: declarative expression does not execute when a decision rule
provides no return value.

Performance

The Pega Platform does not limit the number of nodes in a map value. However, as a best practice to avoid
slow performance when updating the form and also avoid the Java 64KB code maximum, limit your map
value rules to no more than 300 to 500 rows.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Parent class

Through directed inheritance, the immediate parent of the Rule-Obj-MapValue class is the Rule-Declare-
class. However, despite the class structure, this rule type does not produce forward or backward chaining.
Technically, it is not a declarative rule type.

Standard rules

The Pega Platform includes a few standard map values that you copy and modify. Use the Records Explorer
to list all the map values available to you.

Applies
Map Name Purpose
To

Selects a correspondence type based on an input value. For example, if the

input value is "Home Address", the correspondence type result is Mail.
Data- SetCorrPreference
Allows outgoing correspondence to be sent based to on available addresses,
for a Data-Party object.

Can associate an Operator ID or email addressee with officers based on the

Work Officers
titles CEO, CFO, COO, and VP. (Cells are blank in the standard rule.)
 About Decision Trees
Decision tables

Configuring rows and columns in a map value

Complete the fields in the Input Rows and Input Columns sections of the Configuration tab to guides your
inputs on the Matrix tab of a map value.

Evaluation of a map value can be based on the value of properties (specified here as the Row Property and
Column Property), or on the value of parameters specified in a method.

If you leave the Property fields blank, the method must specify parameter values that match or are
converted to the Data Type values on this tab.

When the Property fields are not blank but the activity step used to evaluate the rule specifies a parameter,
the parameter value in the activity step is used, not the property value.

Input Rows

Field Description

Row
Parameter

Select String, integer, double, Boolean, Date, or DateTime to control how the system makes
comparisons when a row parameter is supplied. It uses the Java compareTo( ) method when
comparing two dates or two strings.

For example, if the method parameter is "007" and the Data Type is String, then a
comparison of "007" < "7" is true. If the method parameter is "007" and the Data Type is
Data Type Number, then the comparison of "007" < "7" is false.

For Booleans, only the "=" comparison is available.

The Data Type field is ignored (and becomes display-only on the form) when the Row
Property property is the source of a value for the map value. Comparisons in that case
depend on the type of that property.

Row
Property

Optional. If this map value is to obtain the row input value from a property, select or enter a
property reference or linked property reference. If you leave this blank, the calling method
Property must supply a parameter value for the row.

For a map value that is "called" by another map value, this field is required.

Label Enter brief text that becomes a row name on the Matrix tab.

Input Columns

Select none as the Column Parameter Data Type when defining a one-dimensional map value.

Complete these optional fields to define a two-dimensional map value, which can be evaluated by the
Property-Map-ValuePair method.

Field Description

Column
Parameter

Select String, integer, double, Boolean, Date, or DateTime to define a two-dimensional map value and
to control how the system makes comparisons when a column parameter is supplied. It
uses the Java compareTo() method when comparing two dates or two strings.
 Field To create a one-dimensional map value,Description
select none. For Booleans, only the "=" comparison
Data Type is available.

The Data Type field is ignored (and becomes display-only on the form) when the Column
Property property is the source of a value for the map value. Comparisons in that case
depend on the type of that property.

Column
Property

Optional. If this map value is to obtain a column input value from a property, select or enter
a property reference or linked property reference. If you leave this blank but use a two-
Property dimensional matrix, the calling method must supply a parameter value for the column.

For a two-dimensional map value that is called by another map value, this field is required.

Label Enter brief text that becomes a column name on the Matrix tab.

About Map Values

Unit testing a map value

You can test a map value individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Testing a map value involves specifying a test page for the rule to use, providing sample values for
required parameters, running the rule, and then examining the test results.

1. In the navigation pane of Dev Studio, click Records Decision Map Value , and then click the map
value that you want to test.
2. Click Actions Run .
3. In the Test Page pane, select the context and test page to use for the test:
a. In the Data Context list, click the thread in which you want to run the rule. If a test page exists
for the thread, then it is listed and is used for creating the test page.
b. To discard all previous test results and start from a blank test page, click Reset Page.
c. To apply a data transform to the values on the test page, click the data transform link, and then
select the data transform you want to use.
4. Enter sample values to use for required parameters in the Results pane and then click Run Again.
Result: The value that you enter and the result that is returned are the values that are used for the
default decision result assertion that is generated when you convert this test to a test case.
5. Optional: To view the pages that are generated by the unit test, click Show Clipboard.
6. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
7. Optional: To view the row that produced the test result, click a Result Decision Paths link.

About Map Values

Unit testing individual rules
Using the Clipboard tool
Opening a unit test case
Application debugging using the Tracer tool

When Condition rules

A when condition rule evaluates a Boolean logical statement involving comparisons among values of
properties, to return true or false.

The following tabs are available on this form:

Conditions
Advanced

Where referenced
Rules of many other rule types can reference when condition rules. For example, you can reference when
condition rules in activities, flows, and through the <pega:when > JSP tag in HTM and XML rules.

Access
Use the Application Explorer to access when condition rules that apply to the work types in your application.
Use the Records Explorer to list all when condition rules available to you.

Development
Many when condition rules can be conveniently expressed as one or more Boolean expressions
(comparisons or function calls) ANDed or ORed together. Use the Conditions tab to enter or update such
rules. Other when condition rules require more complex logic to combine the Boolean expressions. Use the
Advanced tab to enter or update those rules.

Delegation
After you complete initial development and testing, you can delegate selected rules to line managers or
other non-developers. Consider which business changes might require rule updates and if delegation to a
user or group of users is appropriate.

For more details, see Delegating a rule or data type.

Category
When condition rules are part of the Decision category. A when condition rule is an instance of the Rule-Obj-
When rule type.

Creating a When rule

Evaluate a Boolean logical statement that involves comparisons among values of properties, to return
true or false, by creating a When rule.

Defining conditions for a When rule

Enter or revise a When rule that can be expressed as a single Boolean expression or the conjunction
(AND or OR) of one or more Boolean expressions.

Editing a When rule in the legacy mode

Apply functions and more advanced logic in When rules by editing the conditions in the legacy
authoring mode.

Configuring advanced options of a When rule

Define complex logic strings and use functions in conditions by configuring advanced options of a
When rule.

Specifying pages and classes of a When rule

Ensure that a When rule accesses or updates information on clipboard pages by specifying the page
name and class of the pages. At run time, these pages contain the properties that are referenced on
the other tabs of a When rule.

More about When Condition rules

You can compare the value of one property reference against a literal constant, or against the value of
another property reference. If you define more than one comparison, you can combine the results with
and, or, and not operations to determine the final true/false outcome.

Unit testing a when rule

Creating a When rule

Evaluate a Boolean logical statement that involves comparisons among values of properties, to return true
or false, by creating a When rule.

For example, you can create a When rule to prompt a user to enter a delivery address only when the user
specifies that the delivery address varies from the address of residence.

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

2. Expand the Decision category, and then click When.
3. On the When tab, click Create.
4. In the Label field, enter a description of the When rule.
Create names of when condition records that logically follow the word when.
For example: Enter IsTaskCompleted.
5. Optional: To enter a when expression that evaluates whether a value is true or false, click Show
additional options, and then enter the expression. For example: .BalanceRemaining > 0.0
6. Optional: To enable editing the rule in the legacy mode, click Show additional options, and then
select the Use legacy authoring mode check box.
By default, you edit conditions in the condition builder. For more information, see Defining conditions
for a When rule.
7. In the Context section, select an application to which the rule applies.
8. In the Apply to field, select a class to which the rule applies.
9. In the Add to ruleset field, select a ruleset for the rule.
10. Optional: To enable traceability of the rule, in the Current work item section, enter the work item to
associate with the rule, for example, a bug ID.
11. Click Create and close.

When Condition rules

More about When Condition rules

Defining conditions for a When rule

Enter or revise a When rule that can be expressed as a single Boolean expression or the conjunction (AND
or OR) of one or more Boolean expressions.

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

2. From the list of When instances, select a When rule that you want to edit.
3. On the rule form, click the Conditions tab.
4. In the first field, select a value or a property from the list.
5. In the second field, select a comparator from the list.
6. In the third field, enter a value that you want to compare with the value from the first field.

The system compares the value of this field to the value of the corresponding field or condition in the
first column.

For example: Status work is equal to Done

7. Optional: To specify additional conditions and define the relationships between them by performing
the following actions:
a. Click the Add a row icon and add as many conditions as you need.
b. In the drop-down lists between each pair of conditions, specify how these conditions relate to
each other.
You can group conditions with AND or OR operators.
c. In the drop-down list in the upper right corner, specify how you want to evaluate condition
groupings
Group ANDs - Select this option if you want conditions linked with the AND operator to be
evaluated as a group, and conditions linked with the OR operator to be evaluated
individually. With this grouping, the grouping of condition 1 AND condition 2 OR condition 3
OR condition 4 is evaluated as (1 AND 2) OR 3 OR 4. That is, either conditions 1 and 2 must
both be true, or either one of conditions 3 and 4 must be true.
Group ORs - Select this option if you want conditions linked with the OR operator to be
evaluated as a group, and conditions linked with the AND operator to be evaluated
individually. With this grouping, the grouping of condition 1 AND condition 2 OR condition 3
OR condition 4 is evaluated as 1 AND (2 OR 3 OR 4). That is, both condition 1 and one of
conditions 2, 3, and 4 must be true.
Use advanced logic - Select this option if you want to define a mix of grouping by the AND
and OR operator. Use the Logic string field to specify the condition grouping.Note: If you
 change a condition that uses advanced logic back to Group ANDs or Group ORs, all the
groupings that you previously defined are reset.
Tip: Conditions that are evaluated as a group are displayed on a single block of gray background.
8. Click Save.

Building expressions with the Expression Builder

When Condition rules
Creating a When rule
More about When Condition rules

Editing a When rule in the legacy mode

Apply functions and more advanced logic in When rules by editing the conditions in the legacy authoring
mode.

Before you begin: Enable the legacy authoring mode for the rule that you want to edit. For more
information, see Creating a When rule.

By default, when you create and edit When rules, you use the condition builder view. For more information
on how to define conditions, see Defining conditions for a When rule.

1. In the navigation pane of Dev Studio, click Records Decision When , and then open the rule that you
want to edit.
2. On the rule form, double-click the link below the When node.
3. In the first field, enter a property, a literal constant, or a function call.
4. In the second field, select a comparator.
5. In the third column, provide a value that you want to compare with the value from the first field:
Enter the value.
Click Select values, and then select the value.
For example: Status work is equal to Done
6. Optional: To configure advanced conditions, press the Down arrow button, and then select a
condition from the list.
7. Click Submit.
8. Optional: Develop the rule by clicking Actions, and then performing one of the following procedures:
To update the condition, click Edit.
To add another condition, click Insert condition.
To create a group of nested conditions, click Insert group.
To delete the expression node, click Delete.
9. Click Save.

Result: The system displays the conditions and logical operators that you enter on the Advanced tab in
the Condition array and the Logic String field.

When Condition rules

More about When Condition rules

Configuring advanced options of a When rule

Define complex logic strings and use functions in conditions by configuring advanced options of a When
rule.

For example, if you create conditions 1, 2, 3, and 4, you can define an advanced logic string for the
conditions, such as 1 AND (2 OR (3 AND 4)) .

Note: As a best practice, use the Conditions tab to configure and update the rule. Your configuration
populates the conditions array and the Logic String field on this tab. If you add, change, or delete rows, or
edit the Logic String field, you can no longer use the Conditions tab. Updating values in conditions or
using the Options area does not disable that tab.

1. In the navigation pane of Dev Studio, click Records Decision When , and then open a rule that you
want to edit.
2. On the rule form, click the Advanced tab.
3. In the drop-down list, select an expression type.
4. Enter a label for the expression, for example, A.
 5. Complete an expression.
6. If you want to add more expressions, click Add condition, and then repeat steps 3 trough 5.
7. In the Logic string field, enter the Boolean logic operations performed on the Conditions array to
evaluate if the condition is true or false at run time.
If you created the conditions on the Conditions tab, the system populates this field by using the AND
and OR operators, in addition to the group hierarchies that are defined on the condition tree.

You can use and, or , and not in the statement. Use parentheses to control the order of evaluation.

For example: (A and B) or (C and not D) Result: When you save the rule, if the form contains only one test
row, the system inserts the label for that test row in the Logic string field. If you have more than one
row, the system requires all rows to be true. If you want a different outcome, revise and save the
statement again.
8. Optional: In the Advanced options section, in the Allowed functions field, select a function alias
that restricts the available conditions to the one in this field by clicking Add function.
If you add multiple functions, the top entry is the default one.
9. Click Save as.

When Condition rules

Creating a When rule
More about When Condition rules

Specifying pages and classes of a When rule

Ensure that a When rule accesses or updates information on clipboard pages by specifying the page name
and class of the pages. At run time, these pages contain the properties that are referenced on the other
tabs of a When rule.

Define the pages and classes of a rule to:

Set up rule prompting during rule configuration.

Configure rule validation.
Apply default class for list elements.

For more information about pages and classes, see Defining the pages and classes of a rule.

1. In the navigation pane of Dev Studio, click Records Decision When , and then open the rule that you
want to edit.
2. On the rule form, click the Pages & Classes tab.
3. In the Page name field, enter the name of the page that contains the property that is referenced in
this rule.
4. In the Class field, select the class of the page.
5. To add more pages and classes, click Add item, and then repeat steps 3 and 4.
6. Click Save.

When Condition rules

Creating a When rule
More about When Condition rules

More about When Condition rules

You can compare the value of one property reference against a literal constant, or against the value of
another property reference. If you define more than one comparison, you can combine the results with and,
or , and not operations to determine the final true/false outcome.

Conditions in activity steps

Each activity step may reference none or several when condition rules, as preconditions for a method, or
transitions between the just-completed method and the next step.

As a precondition, a condition rule determines whether the method in the activity step executes or skipped.
Referenced in a transition, a condition determines what activity processing flows after completion of the
current activity step.
Standard function
To execute a when condition rule in an expression or in the context of Java code, call the standard function
callwhen() in the Pega-RULES Default library.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

When Condition rules

Creating a When rule

About Constraints rules

Create constraints rules to define and enforce comparison relationships among property values. Constraints
rules can provide an automatic form of property validation every time the property's value is "touched", in
addition to the validation provided by the property or other means.

The following tabs are available on this form:

Constraints

The system evaluates constraints automatically each time a property identified in a constraints rule is
changed. This technique is known as forward chaining.

Where referenced
No other rules explicitly reference constraints rules. When you save a constraints rule, it is enforced
immediately and thereafter. The system automatically adds a message to any property that is present on
the clipboard and fails a constraint. This message marks the page containing the property as invalid and
ordinarily prevents the page from being saved.

Use the Application Explorer to access the constraints rules that apply to work types in your application.
Use the Records Explorer to list all the constraints rules available to you.

After you complete initial development and testing, you can delegate selected rules to line managers or
other non-developers. Consider which business changes might require rule updates and if delegation to a
user or group of users is appropriate. For more details, see Delegating a rule or data type.

Category
Constraints rules are instances of the Rule-Declare-Constraints class. They are part of the Decision
category.

Note the s in the rule type. The Rule-Declare-Constraints rule type replaces the Rule-Declare-Constraint rule
type, which is deprecated.

Constraints rules
Constraints form - Completing the Constraints tab

Record the computations that constrain the property values. Each row defines a separate constraint.
Enter at least one row. Order is not significant.

Constraints form - Completing the Pages & Classes tab

Complete this tab to list the pages referenced by name in the Constraints tab, and to identify the
context of the properties constrained.

More about Constraints rules

Conflicting constraints

Viewing rule history

Constraints rules
Records can be created in various ways. You can add a new record to your application or copy an existing
one. You can specialize existing rules by creating a copy in a specific ruleset, against a different class or (in
some cases) with a set of circumstance definitions. You can copy data instances but they do not support
specialization because they are not versioned.

Create a constraints rule by selecting Constraints from the Decision category. Note: Because constraints extend
the definition of a property value, use nouns in the declarative expression names for better distinction from
property values.

Key parts:

A constraints rule has two key parts:

Field Description

Select a class for this rule. At runtime, a clipboard page of this class must be a top-level
page. The properties to be constrained may be in this class (or in the class of an embedded
page).
Apply to
You cannot use a Rule-Declare-* class or any ancestor of the Rule-Declare - class (including
@baseclass ) here. You cannot use a class derived from the Code- or Embed- class here.

Enter a name for this constraint, unique within the Apply to class. Begin the name with a
letter and use only letters, numbers, the ampersand character, and hyphens.

Identifier No other rules explicitly reference this Identifier value. However, because of normal class
inheritance, a constraints rule named MaximumLimit at one level in the class structure may
override (and so prevent execution of) a constraints rule named MaximumLimit at a higher
level in the class structure.

Rule resolution

When searching for instances of this rule type, the system uses full rule resolution which:

Filters candidate rules based on a requestor's ruleset list of rulesets and versions
Searches through ancestor classes in the class hierarchy for candidates when no matching rule is
found in the starting class
Finds circumstance-qualified rules that override base rules
Finds time-qualified rules that override base rules

About Constraints rules

Viewing rule history
More about Constraints rules

Constraints form - Completing the Constraints tab

Record the computations that constrain the property values. Each row defines a separate constraint. Enter
at least one row. Order is not significant.

When the system detects that a constraint fails, it adds a message to the page of the property identified in
the left portion of the Require That field (if any). The presence of this message ordinarily prevents the
system from saving the page containing this property value to the database.

You can cause a specific additional message ( Rule-Message rule type) to become associated with that
property or another property when the constraint fails, in the Else row.

Detection of this message and any later processing to correct the constraint — such as displaying a
message to a user, recalculation of the property value, and so on — is an application responsibility.

Each property involved in the constraint expression must be on the primary page (the page that has the
class corresponding to the Applies To key part), or on an embedded page identified in Page Context field
on the Pages & Classes tab, or on a linked property page.
Using the controls
Click any constraint to enable controls.

Control Action

open icon Click to review a property (for a field that contains a property reference). If the property does
not exist, click the Open icon to create a new property.

expression
Click the drop-down button to display a drop-down list of all boolean expressions.
selector

Select any constraint to enable. Click the Add a row icon to add a new constraint, or click the
row
Delete this row icon to delete the selected constraint. (Equivalently, use the Insert,
buttons
Shift+Insert, and Delete keys.)

When reviewing this tab, you can see a presentation using either property names or the
Display
Short Description ( pyLabel ) of properties. Click to toggle the display. (Note that two or more
Label
properties may have the same Short Description text.)

Modifying constraints with drag and drop operations

To move a constraint to a different location, click and drag the small circle located to the left of the entry.

To copy a constraint, drag the entry while holding down the CTRL key.

Completing fields

Field Description

Click the drop-down button to select a boolean expression from the drop-down list. The form
changes to reflect the expression selected.
When
Most expressions require properties. Use SmartPrompt to select a property. You can enter a
linked property reference here.

This area defines the constraint. Click the drop-down button to select an expression from the
drop-down list. The form changes to reflect the expression selected.

Most expressions require properties. Use SmartPrompt to select a property, or enter a linked
Require property reference.
that
You can't specify single elements of a Value List, Value Group, Page List or Page Group in property
references here. Use only empty parentheses containing no index or subscript, for example:

pyWorkPage.pyWorkParty().pxCity = "Chicago"

Optional. Type the text of a message within quotes or use the SmartPrompt to select the
name of a Rule-Message. The list of options is limited to Error and blank category messages.
Commonly used messages include:

Else add ValueRequired — Value cannot be null (blank)

message ValueOutOfRange — Value is out of range

Some messages require parameters. To provide fill-in-the-blank text values for each
parameter, follow the message name with a backslash character, the single letter t, and text
for each message parameter.

Optional. Identify the property to be marked with the message. The message remains until
this property has a new value (or until an activity performs a Page-Clear-Messages method).

Ordinarily, choose the property that failed the constraint. Some constraints involve two or
more properties, on the same or different pages. Select the one most likely to have a new
value that will restore the constraint condition.
 Field For example, if the constraint is of the form
Description
BoxWidth IS LESS THAN 40

then the message can be associated with the BoxWidth property. If the constraint has the
form
to
BoxWidth IS LESS THAN BoxLength

then the message can be associated with either property.

In unusual cases, you can leave this blank. When you leave this blank, the message is
associated with the entire page rather than a property on that page. However, this is
temporary, as page messages are removed upon the next user HTTP Submit operation.

You can't use symbolic page names (such as primary or steppage ) here, as they are not
meaningful except within an activity execution context.

About Constraints rules

About Constraints rules

Constraints rules
Viewing rule history
More about Constraints rules

Constraints form - Completing the Pages & Classes tab

Complete this tab to list the pages referenced by name in the Constraints tab, and to identify the context
of the properties constrained.

1. About
2. New
3. Constraints
4. Pages &
Classes
5. History
6. More...

For basic instructions, see How to Complete a Pages & Classes tab.

Field Description

Optional. Identify a page that is the source of properties referenced on the Constraints
tab.
Page
Optionally, add a row with the keyword Top as the page name, to identify a top-level page.
Name
The Top keyword allows you to use the syntax Top.propertyref to identify properties, on
other tabs of this rule form.

Class Optional. Select the class of that page.

The Locate Page Expression option is not supported. Use a data page instead. Rules
Locate
created in previous versions that use the Locate Page Expression display this field. New
Page
rules do not display this field. Changes to a rule that uses this option cannot be saved
Expression
unless Locate Page Expression is replaced by supported functionality.

The Locate Page Activity option is not supported. Use a data page instead. Rules created in
Locate
previous versions that use the Locate Page Activity display this field. New rules do not
Page
display this field. Changes to a rule that uses this option cannot be saved unless Locate
Activity
Page Activity is replaced by supported functionality.
 Page
Field Description
Context
Data

Optional. Leave this blank if the constrained property or properties (on the Constraints tab)
all have mode Single Value.

Otherwise, identify a Page List or Page Group property on the clipboard. You can supply literal
index (subscript) values or property-reference index values. Precede the property reference
with a period.
Page
Context To indicate that all the values of the index are acceptable, omit any index between
parentheses. For example, these are acceptable:

Invoices.py Orders(2).pyItems("Manuals").pyItems

Invoices.py Orders().pyItems().pyItemNames

Optional. If the Page Context field is not blank, identify the class of the page or pages that
Page Class are identified in the Page Context field. (You cannot use the $ANY, $NONE or $CLASS keywords
here.)

About Constraints rules

About Constraints rules

Constraints rules
Viewing rule history
More about Constraints rules

More about Constraints rules

Conflicting constraints

Multiple constraints that are impossible to meet are neither detected or rejected, such as A > B and B > A.
Both properties are marked as not valid each time either is changed.

Primary page

During execution of a constraints rule, the page on which the rule operates temporarily becomes the
primary page. The page keyword PRIMARY and the results of the tools.getPrimaryPage() PublicAPI method
reflect this change. When the constraints rule completes, the primary page of the calling activity resumes
as primary.

Alias Function rules

The contents of the selection lists on the Constraints tab depend on property alias rules and alias function
rules.

Change tracking exceptions

The constraints are tested when a property value on the primary page (the page that matches the Applies
To key part of the rule) changes. The following do not cause the constraints to be evaluated:

Changes to properties on other pages referenced in the Pages & Classes tab
Saving a rule form that contains a property on the page
Retrieving a property value with the Obj-List or Obj-Browse method
Retrieving a property with the RDB-List method, unless the ApplyDeclaratives parameter of that
method is selected

Workstation display of constraint failures

When appropriate, your application can display constraint rule violations immediately as a user changes an
input value on a user form or flow action form, rather than later when the form is submitted. The user can
see the constraint message immediately.

For example, the constraint may require that the Due Date field be at least a week after the Start Date
field. As a user enters and revises work item data, the constraint is checked immediately as user focus
leaves either input field.

This feature can improve user productivity and accuracy, while also reducing the number of server
interactions and HTTP traffic required to complete a valid input form. Consider whether and where such
interactive checking may simplify the user's task of completing complex input forms in your application.

To implement this capability:

1. For best results, use this feature on flow actions or harnesses that use the SmartFrames layout and JSP
tags rather than declaratives.
2. Include the properties involved in the constraints on the same flow action form, or on the same user
form (in the same or different sections). (Don't place the input in the flow action form and the target in
the harness form or vice versa.)
3. Select the Enable Expression Calculation? box on the HTML tab of the Flow Action form or Harness
form.
4. Test.

This feature is based on AJAX technology.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Testing and debugging constraints rules

Using the Tracer, you can watch the evaluation of a constraints rule. Start the Tracer and select a requestor
session. Click Settings and check the Declare Constraint box in the Event Types to Trace section. Also
check the RuleSet that contains the rule to be traced.

The statistic Tracked Property Changes on the full details page of the Performance tool shows how many
property changes have occurred (for the current requestor since log-in) that are tracked for declarative
rules computations. You can modify the prlog4j2.xml file to log additional details about tracked property
changes. See the Pega Community article How to determine which properties are tracked for declarative
processing .

OnChange activities

Constraints rules, like Declare Expression rules, do not evaluate during the execution of an OnChange
activity.

Viewing test coverage reports

Viewing test coverage reports
Application debugging using the Tracer tool
About Constraints rules
Constraints rules
Viewing rule history

About Declare Expression rules

Use Declare Expression rules to define automatic computations of property values based on expressions.

The following tabs are available on this form:

Expressions
Change Tracking

Note: The Change Tracking tab has been removed from the declare expression rule form as of Pega
Platform 8.3. If you want to use the Change Tracking tab when configuring your declare expression,
click Actions Use legacy expression .

Note: Do not confuse Declare Expression rules with simple expressions. Expressions — a syntax that
includes constants, function calls, operators, and property references — are used in many situations in
addition to Declare Expression rules.

Forward chaining
Often, target property values are computed automatically each time any of the other input values in the
expression change, or when a value for this property is accessed, changed, or using other criteria. This
technique is known as forward chaining.

For example, you can declare that a property named Order.TotalPrice is always the sum of:

OrderLine(1).TotalPrice
OrderLine(2).TotalPrice
OrderLine(3).TotalPrice

and so on. You can also declare that OrderLine().TotalPrice is always equal to .Quantity multiplied
by.UnitPrice.

Backward chaining
In an activity, the Property-Seek-Value method can access the computational relationships among
properties in a Declare Expression rule to identify source values needed to compute a missing property
value. This technique is known as backward chaining.

For example, consider a single Declare Expression rule defining Circumference as 3.1416 times Diameter
with Change Tracking set to Whenever used. This rule can be used in either forward-chaining or backward-
chaining mode:

If step 3 of an activity causes the value of Diameter to be set, an updated value for the Circumference
property is available at the start of step 4 (forward chaining).
If step 1 of another activity uses the Property-Seek-Value method with Circumference as the target,
and no value for Circumference is found, the system seeks a value for Diameter (backward chaining).

Access
Use the Application Explorer to access the Declare Expression rules that apply to work types in your
application. Use the Records Explorer to list all Declare Expression rules available to you.

After you complete initial development and testing, you can delegate selected rules to line managers or
other non-developers. Consider which business changes might require rule updates and if delegation to a
user or group of users is appropriate. For more details, see Delegating a rule or data type.

Category
Declare Expression rules are instances of the Rule-Declare-Expressions rule type. They are part of the
Decision category.

Note: This rule type name ends with S . The Rule-Declare-Expressions rule type replaces the 03-02 Rule-
Declare-Expression class, which is deprecated.

Declare Expression form - Completing the Change Tracking tab

Complete this tab to determine the conditions that cause automatic recomputation of the expression.
These conditions affect how often the computation on the Expressions tab is performed.

Declare Expressions form - Completing the Expressions tab

On this tab, record the computations for the target property identified in the key.

Creating Declare Expression rules

Declare Expression rules - Completing the Create, Save As, or Specialization form

Declare Expression form - Completing the Pages & Classes tab

Use the Pages & Classes tab to list the pages referenced in the Expression tab. See How to Complete a
Pages & Classes tab for basic instructions.

More about Declare Expression rules

 This topic provides additional information about declare expression rules.

Viewing the declarative network

Quickly gain insight into the relationships between declarative properties, which your system
calculates automatically based on the value of other properties. By accessing the declarative network
you can view and test declarative rules, which reduces processing errors and development effort.

Expressions
Viewing rule history

Declare Expression form - Completing the Change Tracking tab

Complete this tab to determine the conditions that cause automatic recomputation of the expression. These
conditions affect how often the computation on the Expressions tab is performed.

Note: Declare expressions that are created as of Pega Platform 8.3 do not include the Change tracking
tab. To use the legacy declare expression Change tracking tab, click Actions Use legacy expression
.Note: Change tracking applies to properties on the primary page — the page that matches the Applies To
key part of the rule. Changes to properties on other pages referenced in the expression or on the Pages &
Classes tab are not tracked and do not trigger recomputation.

Additionally, the following operations that can change a property value do not cause change tracking to
occur:

Saving a rule form that contains a property

Retrieving a property with the Obj-List or Obj-Browse method
Retrieving a property with the RDB-List method, unless the ApplyDeclaratives parameter of that
method is selected

Note: Forward chaining operates only when the source properties are not marked as invalid. If a property
has an associated message, forward chaining halts.Note: Changes made to a property value within a Java
step of an activity do cause backward changing computations to start, but do not cause forward chaining
computation.
Field Description

Target Select to determine how often Pega Platform recomputes the value of the Target
Property Data Property (identified in the second key part).

Select an option to determine which events cause this rule to run:

Whenever inputs change

(Default). Forward-chaining recomputation. The target property is not recomputed
when the property is used as a source, only when one of the expression inputs
change. If the target property is not present on the page when needed or is
present but has no value, the Declare Expression rule does not run.
When used if no value present
Compute when the value is null, blank, zero, or does not yet appear on the page
using backward chaining. Assuming the computation results are not null, later
requests for the target property do not cause the Declare Expression rule to run.
When used if property is missing
Recomputation using backward chaining when the target property is not present
on the clipboard.
Whenever used

Just-in-time recomputation even when the property already has a value, using
backward chaining. Caution: This choice ensures that the target property value
matches the computed value at the start of every activity step, by evaluating the
rule upon every read access of the target property. Because this choice can be
costly in terms of performance, a warning icon appears when you save the rule
form.

Note: During backward chaining computations, if the Otherwise section of a

decision tree or decision table, or the Default row in a map value referenced in a
Declare Expression rule can be computed, but properties needed for other parts of
 Field the form are not defined, the Otherwise value is returned as the value of the rule.
Description
When applied by a Rule Collection
Calculate
Value The target property is computed only when the defined Declare Expression rule is
invoked by a collection rule. The chained expressions also are evaluated if they too
are set to "When applied by a Rule Collection."

For example, if the defined rule is TotalCostAfterTax=TotalCost*(1+TaxRate)

where TotalCost=ItemCost*Quantity , then this expression is run only when a
collection references this rule. In this case, TotalCost is also calculated if the
properties on it were set to "When applied by a Rule Collection."

This option supports self-referential expressions, for example,

MyProperty=.MyProperty+1

Note: This option is compatible with versions earlier than PRPC 7.1.6.
When invoked procedurally

The target property is computed only when an independent collection rule directly
invokes the target property. If the defined Declare Expression rule is chained into
another expression that is set to "When invoked procedurally," the chained
expression will not run.

For example, if the defined rule is TotalCostAfterTax=TotalCost*(1+TaxRate)

where TotalCost=ItemCost*Quantity , then this expression is run only when a
collection references this rule. In this case, TotalCost is not calculated if the
properties on it were set to "When invoked procedurally."

This option supports self-referential expressions, for example,

Note: As a best practice, select Whenever used when the expression involves values
from properties on multiple pages.

Optional. Enter property references to identify additional properties (in the same page
context) to be tracked. Order is not significant. If not blank, changes to any of the
Additional properties cause this rule to execute.
Dependencies
This array appears only when you select Whenever inputs change for the Calculate Value field.

Select one of three settings to further define which situations cause this expression to
be evaluated:

Only when the top-level page is of the Applies to class

To execute this rule only if the property is on a top-level page.

Note: Do not select this option if the Applies To key part of this rule identifies a
class derived from the Embed- base class; by definition, pages of such classes are
never at the top-level.
When the top-level page is of the Applies To class, or one of the following
To restrict execution to contexts in which the top-level page matches the Applies
Context To class, one of a specified list, or any descendent classes in the class hierarchy.
Execution Regardless of any pages it is embedded in
Behavior
To execute the rule regardless of the page context, making this rule completely
"context-free".

Note: If you select this option, you cannot use the Top or Parent keywords in the
computations on the Expressions tab, either explicitly or in decision rules
referenced on that tab.

Caution: The third selection can produce high execution frequencies. Select the most
restrictive value that meets your application requirements.Note: If this Pega Platform
system was upgraded from Version 5.2 or earlier, execution of context-free expressions
 Field is disabled by default. Enable them through changes to the prconfig.xml file or Dynamic
Description
System Settings. See More about Declare Expression rules.
Execute this
Expression

This array appears only if you select the second choice ( When the top-level page...) for the
Execute this Expression field.

Allowed top- Enter a list of classes. Execution occurs if the top-level page has a class that exactly
level classes matches any class on this list, or is a descendent of one of the classes on this list.

Do not list the Applies To key part here; that class is included automatically.

Supported and unsupported configurations in simplified declare expressions

As of Pega Platform 8.3, the Change tracking tab has been removed from the declare expression rule
form to simplify expression configuration. In these simplified declare expressions, some Target
Property Data and Context Execution Behavior configurations are not supported.

About Declare Expression rules

Creating Declare Expression rules
Viewing rule history
More about Declare Expression rules

Supported and unsupported configurations in simplified

declare expressions
As of Pega Platform 8.3, the Change tracking tab has been removed from the declare expression rule
form to simplify expression configuration. In these simplified declare expressions, some Target Property
Data and Context Execution Behavior configurations are not supported.

Note: To access the Change tracking tab, click Actions Use legacy expression .

Supported configurations
In simplified declare expressions the target property's value is only calculated whenever used. Additionally,
expressions are always executed regardless of the context of the pages they are contained in.

Unsupported configurations
The following Target Property Data field options are not supported for simplified declare expressions. For
detailed information about these options, see Declare Expression form - Completing the Change Tracking
tab.

Whenever inputs change

When used, if no value present
When used, if property is missing
When applied by a Rule Collection
When invoked procedurally

The following Context Execution Behavior field options are not supported for simplified declare
expressions. For detailed information about these options, see Declare Expression form - Completing the
Change Tracking tab.

Only when the top-level page is of the Applies To class

When the top-level page is of the Applies To class, or specified Allowed Top-Level Classes

Page context changes

In simplified declare expressions, context-bound rules are not supported.
Non-atomic targets
Non-atomic targets are not supported in simplified declare expressions, for example, .page.targetProp.

About Declare Expression rules

Declare Expression form - Completing the Change Tracking tab

Declare Expressions form - Completing the Expressions tab

On this tab, record the computations for the target property identified in the key.

Using the controls

Click any condition or a comparison to enable controls.

Control Action

Click to review a property (for a field that contains a property reference). If the property does
open icon
not yet exist, click to create a new property.

expression
Click to display a drop-down list of all boolean expressions.
selector

Select a condition to enable. Then click the Add item icon to add a new condition, or click
the Delete row icon to delete the selected entry (Equivalently, use the Insert,
Shift+Insert, and Delete keys). To re-order conditions, you can use the Windows drag-and-
drop operation.
row
buttons If OR is selected as a boolean operator in an expression, click the Add item icon to add a
new comparison, or click the Delete row icon to delete the selected comparison
(Equivalently, use the Insert, Shift+Insert, and Delete keys). To re-order comparisons, you
can use the Windows drag-and-drop operation.

When reviewing this tab, you can see a presentation using either property names or the
Display
Short Description ( pyLabel ) of properties. Click to toggle the display. (Note that two or more
Label
properties may have the same Short Description text.)

Modifying expressions with drag and drop operations

To move a condition or a comparison to a different location, click and drag the small circle located to the
left of the entry.

To copy a condition or a comparison, drag the entry while holding down the CTRL key.

Completing fields

Field Description

Whenever
inputs
change

Click the drop-down button to select a boolean expression from the drop-down list. The
form changes to reflect the expression selected.
If
Most expressions require parameters that may themselves be expressions. Use
SmartPrompt to select a property as a parameter.

"Boolean Depending on the expression selected, choose THEN, OR, or AND operator. If the OR
Operator" operator is selected, you may add comparisons to the expression.
 Field Select a computation type. The choices available depend on the type of the Target Property
Description
.

Keyword
Effect
Value of
Assigns the value of an expression to a property.
Sum of , Minimum of , Maximum of , Average of

Performs the computation indicated based on an aggregate property in the Expression

field When you select any of these four aggregate operators, the Expression field must
identify a single property reference (for example, a Value Group ), not a more general
form of an expression.

This property is set to equal that of the first property with the same name found on a
parent page. Only a property on a page of a class equal to or a descendant of this
expression will be used as input. You can't use a When expression or rule with this
computation type.

Value of first matching property in parent pages

After this expression is defined, the link is immediately established and maintained by
the system.

On the Change Tracking tab, the Calculate Value field must be set to Whenever inputs
' and the Execute this Expression field must be set to ' Regardless of any pages it is
change
embedded in '.

Set This feature is known as property reflection, because the target property automatically
Property updates to reflect the value of the parent property.
To
Performs the computation indicated based on a Page Group or Page List property in the
Expression field.

True if Any Entries of

Applies an OR operation to a list or group of expressions, each of which returns true or
false. Appears when the target property has type TrueFalse.
True if All Entries of
Applies an AND operation to a list or group of expressions, each of which returns true
or false. Appears when the target property has type TrueFalse.
True if No Entries of
Applies a NOT operation to a list or group of expressions, each of which returns true or
false. Appears when the target property has type TrueFalse.
Index for Minimum of
Finds the smallest value among the values in the aggregate property in the Expression
field, and returns the index (subscript) of that value.
Index for Maximum of
Finds the largest value among the values in the aggregate property in the Expression
field, and returns the index (subscript) of that value.
Result of Decision Tree
Evaluates a decision tree and assigns the result to the target property. See More... for
information about special processing that can occur at runtime in this case.
Result of Decision Table
Evaluates a decision table and assigns the result to the target property. See More... for
information about special processing that can occur at runtime in this case.
Result of Map Value
Evaluates a map value and assigns the result to the target property. See More... for
information about special processing that can occur at runtime in this case.

Enter an expression or identify a rule that computes a value for the Target Property . Based
on the Set Property To field, complete this field:

Set property to
Instructions
Value of

Enter an expression, or choose and complete one of the function alias phrases from
 Enter an expression, or choose and complete one of the function alias phrases from
Field the selection list. Enter a pair of Description
double-quotation marks ("") for a null text value.

If the Calculate Value field on the Change Tracking tab is set to Whenever inputs change ,
reference at least one input property on the primary page, the page that matches the
class of the Applies To key part of this rule.

Your expression can reference properties on other pages — listed in the Pages &
Classes tab — using a page name and property reference, but these properties are not
change-tracked. References to aggregate properties apply to all elements of the
property, so include parentheses () with no explicit subscript.

If the Page Context field is not blank, you can use the Parent keyword followed by a
period and property name to identify properties on the immediate parent of the
(no label) primary page, or the Top keyword followed by a period and property name to reference
a property in the top-level page. (You can use the Parent keyword more than once.)

Sum of, Minimum of, Maximum of, Average of, Count of, Index for Minimum of, Index for
Maximum of

Identify a single aggregate property containing the values to be summed, averaged,

and so on. For Sum of and Average of, the property type must be numeric.

References to aggregate properties apply to all elements of the property, so include

parentheses () with no explicit subscript. (You can't use the Top or Parent keywords
here.)

Enter the second key part of a rule of that type. If the Page Context key part is empty,
the system uses the Applies To key part of this rule as the Applies To key part of the
referenced rule.

Result of Decision Tree , Result of Decision, TableResult of Map Value

Otherwise, it uses the class of the Target Property as the Applies To key part. If the
decision tree, decision table, or map value references named pages, identify these
pages on the Pages & Classes tab. (You can't use the Top or Parent keywords here.)

Optional. This field appears only when you select Sum of , Minimum of , Maximum of, Average Of, True if
Any, True if All, True if None , or Count of in the Set Property To field.

Enter an expression that evaluates to true only for those elements of the aggregate
property that you want include in the computation. Leave blank to include all the elements.
using Typically, the expression involves a comparison and a property within the aggregate
entries in property, for example:
which
.Color!="White"

where .Color is an embedded property within a Page List of class Embed-Houses. If the Page List
property contains 100 pages and the Set Property To selection is Count of , this expression
counts how many of the 100 pages have a Color value not equal to "White."

Otherwise
This expression determines the target property value when the conditions array is empty or
Set
all the condition rows evaluate to false. Complete both fields.
Property

Select an expression type such as Value of. This field is similar to the Set Property To field
(no label)
described above.

Enter an expression that computes a value for the Target Property . You can type the
expression directly, or use the Expression Builder. For guided help with composing
expressions, click the Open expression builder icon.
Expression
In the expression, the page that matches the class of the Applies To key part of this rule.
Your expression can reference properties on other pages using a page name and property
reference, but these properties are not change-tracked.
 Field Description
About Declare Expression rules

About Declare Expression rules

Creating Declare Expression rules
Viewing rule history
More about Declare Expression rules

Creating Declare Expression rules

Declare Expression rules - Completing the Create, Save As, or Specialization form

Records can be created in various ways. You can add a new record to your application or copy an existing
one. You can specialize existing rules by creating a copy in a specific ruleset, against a different class or (in
some cases) with a set of circumstance definitions. You can copy data instances but they do not support
specialization because they are not versioned.

Create a Declare Expression rule by selecting Declare Expression from the Decision category. Note: Because
declarative expressions extend the definition of a property value, use nouns in the declarative expression
names for better distinction from property values.

Key parts:

A Declare Expression rule has three key parts:

Field Description

Select an internal or external class for this rule. The properties to be calculated can be in this
class or in the class of an embedded page.

If you select a class derived from the Embed- base class, leave the Page Context key part
blank, which creates a context-free expression.

Apply to Do not use a Rule-Declare- * class or any ancestor of the Rule-Declare- class (including
@baseclass ) here. You cannot use a class derived from the Code- class here.

Do not create rules with Work- as the Apply to class. Instead, choose a class derived from
Work-, such as a work type or work pool container class. In many cases, the Save As dialog
box defaults a container class for this field. See Copying standard rules from the Work- class.

Select a property that appears somewhere within the scope of the class in the Apply to key
part. Precede the name with a period. Select a property of mode Single Value, Page, or Java Property.

Do not use a Declare Expression rule to compute a property for which the Cannot be
Target declarative target box (on the Advanced tab) is selected.
Property
Do not use symbolic page names such as primary or steppage here, because they are meaningful
only in an activity execution context.

Note: If at runtime the Target Property resides on an embedded page rather than a top-level
page, complete the Page Context key part before completing the Target Property key part.

Optional. Leave this blank if the Target Property property has mode Single Value and appears
directly on a page of the Apply to class, or if you are creating a context-free expression.

Otherwise, identify a Page List or Page Group property reference plus parentheses, starting with a
period. Omit any index between parentheses, as the expression applies to all elements. For
example, these show correct use:

.Invoices.pyOrders().pyItems().pyItemNames()

.pxCorrSummary()

Page The length of the value in this field is limited to 64 characters.

 Context
Field Forward chaining does not create embedded pages where none existed before. Declare
Description
Expressions that have a non-blank Page Context and that use top or parent keywords do not
execute unless there is at least one pre-existing embedded page at each level of the page
context. For more information and an example, see the Pega Community article Declare
expression rules using the TOP or PARENT keyword depend on existing pages to run .

When a property is the target of two Declare Expression rules — one context free and the
second with a context, the second takes precedence over the context free rule, which is
ignored. If two context free Declare Expression rules reference the same property using
distinct property reference forms (for example workpage.targetproperty and .targetproperty ),
the rule with the longer reference is executed; the rule with the shorter reference is ignored.

Rule resolution

When searching for instances of this rule type, the system uses full rule resolution which:

Filters candidate rules based on a requestor's ruleset list of rulesets and versions
Searches through ancestor classes in the class hierarchy for candidates when no matching rule is
found in the starting class
Finds circumstance-qualified rules that override base rules
Finds time-qualified rules that override base rules

About Declare Expression rules

About Declare Expression rules

Viewing rule history
More about Declare Expression rules

Declare Expression form - Completing the Pages & Classes tab

Use the Pages & Classes tab to list the pages referenced in the Expression tab. See How to Complete a
Pages & Classes tab for basic instructions.

1. About
2. New
3. Expressions
4. Pages & Classes
5. Change Tracking
6. History
7. More...

Caution: Pages listed here can be the source of property values needed to compute an expression.
However, properties on such named pages are not change-tracked.

This tab is wide. To display more of the content, click the collapse arrow in the portal to temporarily hide
the navigation panel. When you finish working with this tab, click the expand arrow to display the
navigation panel again.

Field Description

Optional. Enter any page referenced by name on the Expressions tab.

Optionally, add a row with the keyword Top as the page name, to identify a top-level page.
The Top keyword allows you to use the syntax Top.propertyref to identify properties, on
Page other tabs of this rule form.
Name Declare Expression rules can apply to embedded pages that appear within top-level pages
with various names. In such cases, you can use the keywords Top or Parent in the page name
here. If the Page Context key part of this rule is not blank, this tab automatically includes a
definition of the Top and Parent keywords.
 Class Optional. Select the class of that page.
Field Description
The Locate Page Expression option is not supported. Use a data page instead. Rules
Locate
created in previous versions that use the Locate Page Expression display this field. New
Page
rules do not display this field. Changes to a rule that uses this option cannot be saved
Expression
unless Locate Page Expression is replaced by supported functionality.

The Locate Page Activity option is not supported. Use a data page instead. Rules created in
Locate
previous versions that use the Locate Page Activity display this field. New rules do not
Page
display this field. Changes to a rule that uses this option cannot be saved unless Locate
Activity
Page Activity is replaced by supported functionality.

Page
Context
Data

If the Page Context key part is not blank, this field identifies the class of the page or pages
Class
that are identified in the Page Context field.

About Declare Expression rules

About Declare Expression rules

Creating Declare Expression rules
Viewing rule history
More about Declare Expression rules

More about Declare Expression rules

This topic provides additional information about declare expression rules.

Avoid direct updates to target properties

Caution: Do not change the value of a property computed by a Declare Expression rule through the
Property-Set method, application of a data transform, or user input into a form. As you develop your
application, the Pega Platform attempts to detect and prohibit such situations.

For example, if someone creates a Declare Expression rule that computes the property AverageWait, a
developer tomorrow cannot save an activity that uses the Property-Set method to change the value of
AverageWait.

However, if yesterday — before the Declare Expression rule was defined — someone created and saved an
activity that set the value of AverageWait, then after today both the activity and the Declare Expression
rule can execute to save the value. This practice is not recommended.

To reduce the risk of similar rule conflicts, you can adopt a naming convention for properties designed to be
computed in Declare Expression rules, and create Declare Expression rules early, using stub or dummy
expressions.

Caution: At run time, the system neither detects nor prevents the value of a target property from
changing through user input, through the Property-Set method, or by data transforms. If the value changes
through these or other direct means, the target property value can temporarily not equal the last computed
expression value. This situation is corrected the next time any input values for the expression change.

How this rule runs with forward chaining

For more information about forward chaining, see forward chaining

If you select Whenever inputs change in the Compute Values field, then each time the value of any property
referenced in any Declare Expression rule — or properties in other rules (such as decision trees, decision
tables, or map values) referenced in the Declare Expression rule — changes, the system computes the
values of the target property.

Ordinarily, code your activity to place all properties of interest on the clipboard before the activity accesses
the value of a property referenced in the key of a Declare Expression rule. Your activity can create
placeholder values (with Property-Set or with a data transform), or create the properties by opening
instances with the Obj-Open method.

If the Declare Expression rule contains a non-blank Page Context field, the expression is evaluated at run
time only when the clipboard contains a page matching that full context.

When more than one Declare Expression rule is to run, you cannot control or predetermine the order in
which the multiple Declare Expression rules run.

Sample rules for backward chaining (goal seeking)

The Property-Seek-Value method uses Declare Expression rules to compute a property value on request.
For an example, the standard flow action named Work-.VerifyProperty calls the standard activity Work-
.VerifyProperty. If you use this flow action in a flow rule, a user can select it to cause the system to use
goal-seeking to compute the value of the pyResolutionCost property.

If the backward chaining process fails, it can indicate a property with no current value that if set could aid
in the computation. Your flow can then prompt a user for help or for a value that can allow the computation
to complete.

Primary Page
During execution of a Declare Expression rule, the page on which the rule operates temporarily becomes
the primary page. The page keyword PRIMARY and the results of the tools.getPrimaryPage() PublicAPI
method reflect this change. When the rule execution completes, the primary page of the calling activity
resumes as primary.

Declarative Network Analysis gadget

In Dev Studio, click Configure Case Management Business Rules Declarative Network to view and
interact with the declarative expression rules in your application.

Alias Function Rules

The contents of the selection lists on the Expressions tab depend on property alias rules and alias function
rules.

Testing and debugging Declare Expression rules

Using the Tracer tool, you can watch the evaluation of a Declare Expression rule. Start the Tracer tool and
select a requestor session. Click Settings and check the Declare Expression box in the Event Types to
Trace section. Also check the RuleSet that contains the rule you want to trace.

The statistic Tracked Property Changes on the full details page of the Performance tool shows how many
property changes have occurred (for the current requestor since log-in) that are tracked for declarative
rules computations. You can modify the prlog4j2.xml file to log additional details about tracked property
changes. See the Pega Community article How to determine which properties are tracked for declarative
processing .

Like other rules, Declare Expression rules won't evaluate as expected if the RuleSets needed for correct
execution are not available to the requestor at run time. For an example, see the Pega Community article
Declarative rules require access to correct input property rules.

Workstation display of calculated values using AJAX

When appropriate, your application can recompute the value of target properties (presented as read-only
fields) immediately as a user changes an input value on a user form or flow action form, rather than later
when the form is submitted. Users can see the new value immediately.

For example, the target property can represent an order total amount for a sales order. As a user enters
and revises sales details, the total changes immediately as user focus leaves an input field.
Note: This feature can improve user productivity and accuracy, while also reducing the number of server
interactions and HTTP traffic required to complete a valid input form. Consider whether and where such
interactive operation can simplify the user's task of completing complex input forms in your application.

To implement this capability:

1. Use this feature on flow actions or harnesses that use the SmartFrames layout and JSP tags.
2. Include at least one input to the expression as another field or flow action. You can't place the input in
the flow action form and the target in the harness form or vice versa.
3. Select the Enable Expression Calculation? box on the HTML tab of the Flow Action form or Harness
form.
4. Test.

This feature uses AJAX between the browser client and the server.

Special processing for map value, decision table, and decision

tree calls
When a Declare Expression rule has Result of decision table, Result of decision tree or Result of map value for the Set Property
To field, special processing occurs at run time when a property referenced in that decision rule is not
present on the clipboard. Ordinarily such decision rules fail with an error message; in this case the system
returns the Otherwise value instead. For details, see the Pega Community article Troubleshooting:
Declarative Expression does not execute when a decision rule provides no return value.

Advanced debugging
Use the Tracer tool to detect that a Declare Expression rule execute when expected. For more detailed
debugging help, use the Logging Level settings tool (or update the prlog4j2.xml file) to include the category
shown here:

<category>
<name="Rule_Declare_Expressions">
<priority value="debug">
</category>

OnChange rules
Declare Expression rules do not evaluate during the execution of an activity of type OnChange. Such
executions are typically brief.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Application debugging using the Tracer tool

About Declare Expression rules
Creating Declare Expression rules
Viewing rule history

Viewing the declarative network

Quickly gain insight into the relationships between declarative properties, which your system calculates
automatically based on the value of other properties. By accessing the declarative network you can view
and test declarative rules, which reduces processing errors and development effort.

1. In the header of Dev Studio, click Configure Case Management Business Rules Declarative
Network .
2. On the Declarative Network Analysis tab, click application, and then select the application whose
declarative network you want to review. Result: The system displays the declarative rules that your
application uses, divided by class.
3. Review the relationship between the declarative rules by performing any of the following actions:
To display the rule and related properties in a pop-up tree diagram, click the Display this top-
level declarative network icon.
To open the declare expression for the rule in a new tab, click the Display declare expression
 icon.
To open the target property of the declarative rule in a new tab, click the property name.
To open the class to which a rule belongs in a new tab, click the class name.

Testing rules in the Declarative Network Viewer

Reduce the number of processing errors by testing calculated properties in the Declarative Network
Viewer.

Business Rules landing page

Testing rules in the Declarative Network Viewer

Testing rules in the Declarative Network Viewer

Reduce the number of processing errors by testing calculated properties in the Declarative Network
Viewer.

By determining the value of a property automatically (declaratively), you reduce the number of manual
calculations required and improve system efficiency. The viewer is a tool that displays the relationship
between declarative properties based on changes to other property values. You can also use the viewer to
test whether the properties calculate correctly, and set up tests for future use.

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

2. Expand the Decision category, and then click Declare Expression.
3. In the list, select the declare expression that you want to test.
4. In the declare expression, click Actions Run .
5. In the Test Page section, select the context to use for the test:
a. In the Data Context list, click the thread in which you want to run the rule.
b. Optional: To discard all previous test results and start from a blank test page, click Reset Page.
6. In the section with the declare expression that you want to test, define the value of the properties that
the system uses to calculate the declarative property:
a. Click a property that you want to define, and then enter its value in the Property field.
b. Click Update.
c. Repeat steps 6.a through 6.b for all properties in the expression.
Result: The value of the declare expression changes to reflect the updated properties. You can now
see whether the declarative property calculates correctly.
7. Optional: To save the settings as a test scenario, click Convert to test , and then complete the New
tab.
For more information, see Creating unit test cases for rules.

Viewing the declarative network

About Declare OnChange rules

Create Declare OnChange rules to run an activity automatically at activity step boundaries when the value
of a specified property changes. This capability provides a form of automatic forward chaining.

The following tabs are available on this form:

OnChange Properties

For example, a Declare OnChange rule can update a year-to-date counter property (an integer) to track
how many times a work item status changed in value. Another Declare OnChange rule can compute the
average dollar amount of work items entered by a team, in real time.

Declare OnChange rules can force all processing on a work item to be suspended pending an independent
review of the situation. The independent review is supported by one or more flows. This feature can support
compliance, fraud detection, and quality control staffs.

Where referenced
No other rules explicitly reference Declare OnChange rules. After you save a Declare OnChange rule, it is
run immediately and as needed.
Access
Use the Application Explorer to access OnChange rules that apply to work types in your application. Use the
Records Explorer to list all OnChange rules available to you.

Category
Declare OnChange rules are instances of the Rule-Declare-OnChange class. They are part of the Decision
category.

Declare OnChange rules -

Declare OnChange form - Completing the OnChange Properties tab

Define the conditions that will cause this rule to be executed. Specify in an array the properties to be
watched for change.

Declare OnChange form - Completing the Pages & Classes tab

Use this tab to list the pages referenced by name in the OnChange tab. Specify the pages in an array
containing these fields. See How to Complete a Pages & Classes tab for basic instructions.

More about Declare OnChange rules

Pega Platform tracks properties listed in Declare OnChange rules for changed values. After each
activity step, and after forward chaining for Declare Expression rules and constraints rules occurs,
tracked changes start the activity specified on the OnChange Properties tab.

How to implement business exception processing with policy overrides

Through OnChange rules and special flows, your application can create application-wide temporary
pauses in flow processing — for example, to detect and review exceptions, suspect data or special
cases — without altering the flows. This provides an alternative to use of tickets.

Policy overrides and suspended work items

Viewing rule history

Declare OnChange rules -

Records can be created in various ways. You can add a new record to your application or copy an existing
one. You can specialize existing rules by creating a copy in a specific ruleset, against a different class or (in
some cases) with a set of circumstance definitions. You can copy data instances but they do not support
specialization because they are not versioned.

Create a Declare OnChange rule by selecting Declare OnChange from the Decision category.

Key parts:

A Declare OnChange rule has two key parts:

Field Description

Select a class for this rule. At runtime, a clipboard page of this class must be a top-level
page. The properties to be watched may be in this class (or in the class of an embedded
page).
Apply to
You cannot use a Rule-Declare-* class or any ancestor of the Rule-Declare- class (including
@baseclass ) here. You cannot use a class derived from the Code- or Embed- class here.

Enter a unique name for this OnChange rule within the class. Begin the name with a letter
and use only letters, numbers, the ampersand character, and hyphens.

No other rules explicitly reference this Identifier value. However, because of normal class
Identifier inheritance, a Declare OnChange rule named OutofStock at one level in the class structure
may override (and so prevent execution of) a Declare OnChange rule named OutofStock at a
 Field higher levelDescription
in the class structure.

Rule resolution

About Declare OnChange rules

Viewing rule history
More about Declare OnChange rules

Declare OnChange form - Completing the OnChange Properties

tab
Define the conditions that will cause this rule to be executed. Specify in an array the properties to be
watched for change.

Properties, Conditions, and Action

Field Description

This array identifies some of the properties that the rule tracks. Order is not significant.
Properties
See More about Declare OnChange rules for information about the properties tracked by
to Watch
the rule.

Enter the desired property references. Each property entered is monitored for changes.
Identify a property on the top-level page (with a dot followed by the page name) or on a
page identified by the Page Context field on the Pages & Classes tab.

If you list more than one property, they must be on the same page, either the top-level
page or a common embedded page.
(1, 2, 3...)
If you list more than one property, when two or more of the properties change value
(for example, within a single step of an activity) this OnChange activity runs only once.
Start each property reference with a dot. You can't reference a property on a page
other than the page corresponding to the Applies To key part of the rule or on a page
identified by the Page Context field on the Pages & Classes tab.

Conditions

Optional. Identify a when condition rule to be evaluated at the time a property value
changes.

The system uses the Page Context value on the Pages & Classes tab (if not blank) as the
Applies To key part of the when condition rule. If the Page Context value is blank, the
system uses the Applies To key part of this OnChange rule.

Alternatively, you can enter a simple Boolean expression here, for example in one of these
formats:
When
property = "constant value"
property1 > property2

You can reference linked properties in the expression. Don't use a complex Java expression
or an expression that calls a function here.

When this OnChange rule used to suspend work item processing, this when condition is
known as the business exception.

Choose
Action...

Select:
 Choose
Field — To cause all executing
Suspend Work Object flows for a work item to be suspended. See
Description
Action Understanding policy overrides and suspended work items.
Call Activity — For all other OnChange processing.

When True Run and When False Run

Complete these fields when you select Call Activity in the Choose Action field.

Field Description

When
True
Run

Enter the Activity Name key part of an activity to execute when any of the specified properties
change (and the test in the When field evaluates to true). Choose an activity with an Activity
Type of OnChange (recorded on the Security tab). If the activity has input parameters, click
Params to enter literal constant values for them.

Activity The system uses the Page Class value on the Pages & Classes tab (if not blank) as the Applies
To key part of the activity. If the Page Context value is blank, the system uses the Applies To
key part of this OnChange rule.

See More about Declare OnChange rules for more about the activity.

When
False
Run

Optional. Enter the Activity Name key part of an activity to execute when any of the specified
properties change and the test in the When field evaluates to false. Choose an activity with an
When Activity Type of OnChange (recorded on the Security tab). If the activity has input parameters,
False click Params to enter literal constant values for them.
Run
See More about Declare OnChange rules for more about the activity.

Suspend Section
Complete these fields when you select Suspend Work Object in the Choose Action field. See Understanding policy
overrides and suspended work items.

Field Description

Suspend
Section

Policy
Enter the Flow Name key part of a flow to execute to support review of the suspended flow.
Override
Ensure that the flow meets the requirements listed in How to implement business
Flow to
exception processing with policy overrides.
run

Enter the third key part of a field value rule with first key part @baseclass and second key
Error
part pyMessageLabel, or enter literal text between double quotes to identify this source of
message
policy override reviews.

About Declare OnChange rules

Declare OnChange rules -
Viewing rule history
More about Declare OnChange rules

Declare OnChange form - Completing the Pages & Classes tab

Use this tab to list the pages referenced by name in the OnChange tab. Specify the pages in an array
containing these fields. See How to Complete a Pages & Classes tab for basic instructions.

1. About
2. New
3. OnChange
Properties;
4. Pages & Classes
5. History
6. More...

If the watched properties are an aggregate or are on an embedded page, complete the Page Context Data
fields.

Field Description

Pages
and
Classes

Optional. Name of a page referenced on the OnChange Properties tab.

Page You can identify named pages here to support evaluation of a when condition rule referenced
Name on the OnChange Properties tab. However, all tracked properties must be on the page
corresponding to the Applies To key part, or a context within that page.

Class Optional. Select the class of that page.

Page
Context
Data

Optional. Leave this blank if the monitored properties are Single Value properties that appear on a
top-level page.
Page
Otherwise, identify a Page List or Page Group property reference on the page. You can supply literal
Context
index (subscript) values or property-reference index values. Omit any index to indicate that all
values of the index are acceptable.

Page Optional. Identify the class of the page or pages that are identified in the Page Context field.
Class You cannot use the keywords $ANY, $NONE or $CLASS here.

About Declare OnChange rules

About Declare OnChange rules

Declare OnChange rules -
Viewing rule history
More about Declare OnChange rules

More about Declare OnChange rules

Pega Platform tracks properties listed in Declare OnChange rules for changed values. After each activity
step, and after forward chaining for Declare Expression rules and constraints rules occurs, tracked changes
start the activity specified on the OnChange Properties tab.

Properties tracked by the OnChange rule

This rule tracks the following properties:

Properties identified in the Properties to Watch field

Properties used in the when condition rule identified in the When field
 Properties used in the decision rules referred by the when condition rule

Restrictions for OnChange activities

The activity identified on the OnChange Properties tab must have an Activity Type of OnChange. It can call or
branch to other activities, but only if they too have an Activity Type of OnChange.

Your activity can examine the Value List property pyChangedProperties to discover the property that changed
value. This property is on the page named pyDeclarativeContext, of class Code-Pega-DeclarativeContext .
This page exists only while the activity runs.

The primary page passed to OnChange activities is the top-level page.

OnChange processing may start as the result of a user HTTP Post operation. If users complete an HTTP form
that changes the value of a property tracked by a Declare OnChange processing, this change is detected.

Use care not to start an infinite processing loop within declarative rules. For example, in an OnChange
activity, do not update any of the properties that caused the activity to start. You can to update other
properties in the OnChange activity.

Declare Expression rules do not evaluate during the execution of an OnChange activity. However, do not
attempt in an OnChange activity to overtly set the value of a property that is the target of a Declare
Expression rule.
Similarly, constraints rules do not evaluate during the execution of an OnChange activity.

Primary page
During execution of a Declare OnChange rule, the page on which the rule operates becomes the primary
page. The page keyword PRIMARY and the results of the tools.getPrimaryPage() PublicAPI method reflect this
change. When the Declare OnChange rule execution completes, the primary page of the calling activity
resumes as primary.

Performance
Design the OnChange activity to execute quickly, as some properties may change values often. Remember
that properties may change values (and thus cause the rule to run) during development and testing tasks,
such as the preview of a harness or flow action form.

Declare OnChange rules may be expensive (computing several values) compared with Declare Trigger rules
that test the same property. Consider which rule type better meets your needs. For example, if a value
changes every few seconds but is part of an object that is saved only hourly on average, a Declare Trigger
rule computes a new value only hourly, not in real time.

Testing and debugging Declare OnChange rules

Using the Tracer, you can watch the evaluation of a Declare OnChange rule. Start the Tracer and select a
requestor session. Click Settings and check the Declare OnChange box in the Event Types to Trace
section. Also check the RuleSet that contains the rule to be traced.

The statistic Tracked Property Changes on the full details page of the Performance tool shows how many
property changes have occurred (for the current requestor since log-in) that are tracked for declarative
rules computations. You can modify the prlog4j2.xml file to log additional details about tracked property
changes. See How to identify which properties are tracked for declarative processing .

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Application debugging using the Tracer tool

About Declare OnChange rules
Declare OnChange rules -
Viewing rule history

How to implement business exception processing with policy

overrides
Through OnChange rules and special flows, your application can create application-wide temporary pauses
in flow processing — for example, to detect and review exceptions, suspect data or special cases — without
altering the flows. This provides an alternative to use of tickets.

For a background on the benefits and purposes of this capability, see Understanding policy overrides and
suspended work items.

Configuration overview

This facility requires three components:

A property or properties present in a work item that can signify a business exception.
An OnChange rule that responds to a business exception by promptly suspending all assignments on
all currently executing flows for the work item.
A flow that supports independent review of the work item, allowing the reviewer to record a final
verdict.
A reviewer — an operator holding the Work-.ReviewPolicyOverrides privilege — who assesses the
business exception and records, in the work item history, a verdict allowing normal flow processing to
resume or end.

1. Define the business exception as a when condition rule

1. Identify the property or properties that are involved in the test.

2. Create a when condition rule that is true only when the property or properties assume an unlikely,
suspect, or potentially erroneous values. Choose a condition that is rare; that for most work items is
false at all times from initial entry through resolution.

2. Create a policy override review flow

1. Create a flow rule to support review of work items that become suspended when the business exception
occurred. On the New dialog box, select PolicyOverride in the Template field. Design the flow to meet these
criteria:

Applies to the class of the suspended work item (or a parent class).
Does not create a new work item.
Does not change the work item status.
Calls, as the last shape before the End shape, the standard flow Work-.FinishPolicyOverride.

This flow may be simple — containing only the Start, End Flow, and Subprocess shapes — or it may require
multiple assignments performed by multiple operators. Use the standard flow Work-.PolicyOverride as a
starting point.

In the SubProcess Properties panel, complete four flow parameters for the Work-.FinishPolicyOverride flow,
to control the email correspondence it produces. You can send correspondence when the review results in a
Deny verdict, and when it results in an Allow verdict.

3. Create an OnChange rule

The OnChange rule detects the business exception and starts the review flow.

1. Select the work type of the work items as the Applies To class.
2. Complete the OnChange Properties tab. In the When field, reference the when condition rule created in
step 1 above.
3. In the Choose Action field, select Suspend Work Object .
4. Identify the review flow in the Policy Override flow to run field.
5. Enter text such as "Too many payees" or the key to a message rule in the Error Message field,
characterizing the reason for the suspension.

4. Adjust the routing

By default, the Work-.FinishPolicyOverride flow creates an assignment on the worklist of the operator
administrator@org.com, where org.com is the organization owning the work item.

1. Override the router activity Work-.ToPolicyOverrideOperator to route this assignment to a person (or one
of a group) who is appropriate to act as a reviewer.

2. Ensure that the Operator ID of this person acquires the privilege Work-.ReviewPolicyOverrides. The
standard role PegaRULES:SysAdm4 conveys this privilege, but you can create other roles appropriate to
your application and organization.

Use the Tracer tool to test such flows.

5. Ensure that reviewers complete their assignments

Each person who acts as a reviewer must review and act on assignments which have the status Pending-
PolicyOverride. To verdict, they can choose Allow or Deny as the flow action.

If they choose Allow, processing resumes and any suspended assignments reappear in worklists or work
queues. If they choose Deny, the work item status changes to Resolved-Revoked. Affected users may be notified
by email, if configured in the flow. In the unusual case that two or more reviews are underway for one
suspended work item, the status changes occur only after all the reviews are complete.

6. Periodically monitor outstanding flow errors

Suspended work items remain suspended until all open reviews are completed.

To see a report of suspended work items, in the header of Dev Studio, click Configure Case Management
Tools Work Admin Suspended Work in Current Work Pool .

To see a list of assignments in suspense, in the header of Dev Studio, click Configure Case Management
Tools Work Admin Suspended Work Assignments .

Note:

This capability illustrates how procedural rules — such as the flows — can operate with declarative
rules — such as the OnChange rules — to directly support business processing. Pegasystems identifies
this distinctive combination as the Pro-Dex capability.
The Show Policy Override button appears at run time on flows (created or updated in PRPC Version
4.2 SP6 and later) for users who have the @baseclass.FlowViewProDex privilege. This button does not
appear on flow actions for which the Auto- generated HTML box on the HTML tab is not selected.

Process category

About Declare OnChange rules

Declare Trigger rules

To define correlations between events in your case types, create Declare Trigger rules to cause an activity
to run when a specified event takes place in a case. By creating Declare Trigger rules, you automate your
business processes and flexibly respond to dynamic business needs.

Declare Trigger rules are a part of the declarative rules that implement the declarative programming
paradigm in Pega Platform.

For each Declare Trigger rule, Pega Platform monitors database operations for objects that you specify as
the Applies To class, and concrete classes that are derived from that class, such as a class that stores your
case type. When a change affects a specified property, Pega Platform uses the Change Tracking feature to
monitor updates to the property values and run triggers accordingly.

For example, a Declare Trigger rule can invoke an activity each time a user changes a postal code in their
personal details. By changing their postal code, the user modifies a Data-Party.pyPostalCode property in an
instance of the Data-Party-Person class. The activity that you specify in the Declare Trigger rule sends an
email message to the customer service representative (CSR) whose territory includes the new address.
Similarly, a Declare Trigger rule can implement a form of logging or audit history for a class by recording
the date, time, and other facts. You can run Declare Trigger rules in the following scenarios:

Page Save
In context
In background
Page Delete
 Page Commit

Nested Declare Trigger rules

To resolve complex use cases, you can nest a Declare Trigger rule within another Declare Trigger rule.
Nested Declare Trigger rules work in the context of the other Declare Trigger rule. For example, you can
define a Declare Trigger rule that sends an email to a CSR when a customer updates their address details.
Then you can create and nest another Declare Trigger rule that creates a document with the updated
details after the case moves to the next stage. You can only nest rules of the Save and Save and types that
run immediately. Nesting rules in the context of the Commit type rules might result in adding an excessive
number of deferred operations during one database transaction. To avoid recursion during nesting of
declare triggers, you can only nest a trigger in a trigger that is not already running on a page in the
execution stack. For example, if a Page A save leads to a save of Page B and a trigger on Page B again
leads to a save of Page A, the declare trigger does not run again on the Page A save.

The following figure presents how nested Declare Trigger rules start events in a case:

Triggering events in a case

To nest triggers, set the value of the declaratives/nestedTriggersEnabled dynamic system setting to true.
For more information, see Creating a dynamic system setting.

Applying Declare Trigger rules

Immediately after you save the rule, your application runs a Declare Trigger rule according to your provided
configuration.

Creating Declare Trigger rules

Define correlations between events in your case types by creating Declare Trigger rules. Declare
Trigger rules run activities as a response to a specified event in a case. As a result, you provide
flexible applications that precisely meet your business needs.

Declare Trigger form - Completing the Pages & Classes tab

Use this tab to list the clipboard pages referenced by name in the Triggers tab. See How to Complete a
Pages & Classes tab for basic instructions.

More about Declare Trigger rules

Create Declare Trigger rules to cause an activity to run when instances of a specific class are created,
updated, or deleted in the database. This implements a form of forward chaining.

Viewing rule history

Building logic and calculating values in your application

Creating Declare Trigger rules

Define correlations between events in your case types by creating Declare Trigger rules. Declare Trigger
rules run activities as a response to a specified event in a case. As a result, you provide flexible
applications that precisely meet your business needs.

For example, you can define a Declare Trigger rule that sends an email to a customer service
representative (CSR) after a customer changes a postal address in a case.
Declare Trigger rules invoke activities when your application creates, updates, or deletes a class in the
database. Operations on classes are related to actions in a case, such as saving a case or updating
information in a case. You can also use Declare Trigger rules to track property changes, and for auditing
purposes.
1. In the header of Dev Studio, click Create Decision Declare Trigger .
2. In the Label field, provide a descriptive name for the rule that you want to create.
3. In the Context section, specify where your application stores the rule:
a. From the list of application layers, select an application to store the rule.
b. In the Apply to field, enter the class to which the rule applies.
At run time, the system monitors property values in this class and classes that inherit from this
class.
c. In the Add to ruleset list, select a ruleset and a ruleset version in which to store the rule.
4. Click Create and open . Result: The rule form opens.
5. On the Triggers tab, in the Trigger when an instance is list, select a type of event to trigger the
rule:
Choices Actions

Run the rule when an application

deletes an instance in the Select Deleted.
specified class

Run the rule when an application

saves an instance of the specified Select Saved.
class

Run the rule when a Commit

method occurs for a saved Select Committed Save.
instance of the specified class

Run the rule when a Commit

method occurs for a deleted Select Committed Delete.
instance of the specified class

a. Select Saved and.

b. In the One of these properties was modified section,
in the Property field, enter a property that you want your
application to track. For example: To track changes of the
postal address, enter Data-Party.pyPostalAddress.
c. Optional: To retain the initial value of the property that
Run the rule when an application changes, in the Copy Value To (optional) field, enter a
saves an instance of the specified property that stores the initial value.
class and specified property Retaining the initial values is useful for auditing purposes
values in the class change and makes the previous property value available to the
second and subsequent runs of the rule.

Copying occurs only if the trigger activity runs, and after

the trigger activity completes.

d. To track changes to more properties, click Add a row, and

then repeat steps 5.b and 5.c.
6. To run the rule only when a case meets specified conditions, in the Condition section, in the When
field, enter a When condition rule.
The system evaluates the conditions at run time and runs the Declare Trigger rule only when the When
condition evaluates to true.
7. In the Trigger activity section, in the Name field, enter the activity that the rule invokes.
8. In the Execute list, determine how the activity runs:
To run the activity during forward chaining, before the commit completes, select Immediately.
To run the activity in a new requestor, outside of the context of forward chaining, select In
Background On Copy.

Note: Ensure that the activity that you select to run in the background includes the Commit
method.

When you select an activity of a different type than Trigger , ensure that the preconditions and
transitions in the activity do not use When condition rules and do not call functions. For more
information about activities, see Creating an activity.Caution: Although your application can contain
multiple Trigger activities for the one class that is specified in the Apply to field, you cannot control
the order in which two or more triggered activities run. Create activities that provide correct results
when running in any order, and when running either independently or simultaneously.
 9. Click Save.

Declare Trigger rules

Viewing rule history
More about Declare Trigger rules

Declare Trigger form - Completing the Pages & Classes tab

Use this tab to list the clipboard pages referenced by name in the Triggers tab. See How to Complete a
Pages & Classes tab for basic instructions.

1. About
2. New
3. Triggers
4. Pages &
Classes
5. History
6. More...

Field Description

Pages
and
Classes

Optional. Enter the name of a page referenced on the Triggers tab. Optionally, add a row with
Page
the keyword Top as the page name, to identify a top-level page. The Top keyword allows you to
Name
use the syntax Top.propertyref to identify properties on other tabs of this rule form.

Optional. Select the class of the page or pages that are referenced on the Triggers tab. You
cannot use the keywords $ANY, $NONE or $CLASS here.
Class
The system completes the first row of this array, using the Applies To key part of the rule as
the class, and leaving the Page Name field blank. Do not alter that row.

Page
Context
Data

Optional. Leave this blank if the properties watched by this rule (and recorded on the Triggers
tab) are Single Value properties found on a top-level page.

Otherwise, identify a Page List or Page Group property reference on the page. You can supply literal
Page index values or property-reference index values. Omit any index to indicate that all values of
Context the index are acceptable. These are acceptable:

Invoices.pyOrders(2).pyItems("Manuals").pyItemNames
Invoices.pyOrders().pyItems().pyItemNames

Optional. Select the class of the page or pages that are identified in the Page Context field. You
Class
cannot use the keywords $ANY, $NONE or $CLASS here.

About Declare Trigger rules

Declare Trigger rules

Creating Declare Trigger rules
Viewing rule history
More about Declare Trigger rules

More about Declare Trigger rules

Create Declare Trigger rules to cause an activity to run when instances of a specific class are created,
updated, or deleted in the database. This implements a form of forward chaining.

Trigger activities
The primary page passed to Trigger activities is the top-level page corresponding to the Applies To class of
the rule.

An activity of type Trigger may alter properties, call functions and execute other rules, but do not perform
database commits. Take care in declarative processing not to specify processing that produces infinite
looping.

When you choose In Background on Copy in the Execute field, the triggered activity runs in a child requestor in
parallel to the current requestor. This means that:

The triggered activity does not appear in your Tracer session

The triggered activity cannot access clipboard pages other than the primary page
Within the triggered activity, the primary page has no name

Primary page
During execution of a Declare Trigger rule, the page on which the rule operates temporarily becomes the
primary page. The page keyword PRIMARY and the results of the tools.getPrimaryPage() PublicAPI method
reflect this change.

When the Declare Trigger rule execution completes, the primary page of the calling activity resumes as
primary.

Testing and debugging

Using the Tracer, you can watch the evaluation of a Declare Trigger rule if the Execute field value is Immediate
:

1. Start the Tracer and select a requestor session.

2. Click Settings and check the Declare Trigger box in the Event Types to Trace section.
3. Select the RuleSet that contains the rule to be traced.

History change auditing

Declare Trigger rules can automatically update the history of a work item, rule, or data object when certain
properties change.

For work item change tracking, use the Field Auditing gadget, on the Work History landing page.

For data or rule tracking, see the Pega Community article How to audit field-level changes to security rule
and data instances.

You can view the generated Java code of a rule by clicking Actions View Java . You can use this code to
debug your application or to examine how rules are implemented.

Application debugging using the Tracer tool

Declare Trigger rules
Creating Declare Trigger rules
Viewing rule history

Defining conditions in the condition builder

Use the condition builder to create conditions that define the behavior of your application, or to use for
propositions evaluated by a proposition filter. You can save custom conditions to the condition library for
future use.

1. In App Studio, navigate to a condition builder that defines the application element that you want to
edit. For example: The condition builder for refreshing a layout is on the configuration pane of that
layout. For more information, see Defining refresh conditions for UI areas.
 2. Optional: For proposition filters, to remove all previously added criteria from the condition builder,
click Actions Clear all criteria .
3. In the Configure condition section, in the list of values, select a value to evaluate:
To select a field from a data model in your application, click Fields, and then select the field.
To select a when condition from your application, click When conditions, and then select the
condition.
4. In the comparator list, select a comparator.
5. In the value field, enter or select a value that your application compares with the field in the data
model or a when condition. For example: Status work is equal to Done
6. Optional: To add more conditions, click the Add a row icon, and then repeat steps 3 through 5.
7. If you add multiple conditions, between the rows, select the and or or operator to define how to
evaluate the conditions.
You can group conditions using the and or or operators.
Result: If you select and, the condition evaluates to true when all of the rows evaluate to true. If you
select or, the condition evaluates to true if at least one of the rows evaluates to true.
8. In the list in the upper-right of the page, select one of the following options to specify how to evaluate
condition groupings:

To evaluate the conditions that are linked with the AND operator as a group, and to evaluate the
conditions that are linked with the OR operator individually, click Group ANDs.

With this grouping, the grouping of condition 1 AND condition 2 OR condition 3 OR condition 4 is
evaluated as (1 AND 2) OR 3 OR 4. That is, either conditions 1 and 2 must both be true, or either
one of conditions 3 and 4 must be true.

Group ORs - Select this option if you want conditions linked with the OR operator to be
evaluated as a group, and conditions linked with the AND operator to be evaluated individually.

With this grouping, the grouping of condition 1 AND condition 2 OR condition 3 OR condition 4 is
evaluated as 1 AND (2 OR 3 OR 4). That is, both condition 1 and one of conditions 2, 3, and 4
must be true.

To define a grouping by both the AND and OR operators, click Use advanced logic, and then
specify the condition grouping in the Logic string field.Note: If you change a condition that uses
advanced logic for the Group ANDs or Group ORs, all the groupings that you previously defined
are reset.
Tip: Conditions that are evaluated as a group are displayed on a single block of gray background, so
that you can identify them more easily.
9. Optional: To reuse the condition in the future, save the condition to the library:
For conditions in a workflow, click More Add to when condition library .
For conditions in a proposition filter, click Actions Save to library .Note: The Save to library
option is not available if the conditions include either Strategy rules or when conditions with
parameters. The option is also disabled for proposition filters which include default criteria that
are created using the Use advanced logic option.
Result: The conditions are saved to a new when rule in the top level class of the proposition filter. The
system automatically registers the when rule as a relevant record for use in the condition builder.

Defining conditions for skipping a stage

Displaying optional actions conditionally
Displaying supporting processes conditionally
Conditionally starting a process by using a condition
Adding decisions to processes

Building expressions with the Expression Builder

Author expressions using the Expression Builder by completing the following steps:

1. Build the expression.

You can:

Click Browse to open the leftmost panel, which displays the functions and properties that you
can insert into the expression and the search feature.

Click Test so that the enhanced Expression Builder can validate your expression as you enter it.
 Any errors in your expression are displayed above the text editor.

Syntax errors appear next to line numbers in whichever view you enter expressions.

Complete any of the following actions:

Enter all or part of the expression in the text editor, including functions, operators, constants, and
property references or linked property references.

Add properties.

Complete any of the following actions:

Type "." in the text editor and select a property from the list.

Click Properties, select the page from which to reference the property, and drag the
property to the text editor.

Properties can be referenced from four types of pages:

Current Page – Includes a list of properties from your current case context.

Data Page – Includes a list of properties available from application data pages.

Parameter Pages – Includes properties defined as parameters on the invoking rule.

Custom Page – Includes properties from custom pages defined on the Pages & Classes
tab of the invoking rule.

Add a function.

Complete any of the following actions:

Type "@" in the text editor and select a function from the list.

Press Ctrl + the space bar and select a function from st.

Include a function by clicking Functions, selecting the library that contains the function, and
dragging the function to the text editor.

Note: The Expression Builder displays only non-internal functions. To display all functions in the
system, see Displaying all functions in the Expression Builder.

In the text editor, enter an argument value for functions that require arguments.

Search for a property in your current page or for a non-internal function by entering all or part of
the text for which you want to search in the search field and either click either the Search icon or
press Enter. Search results appear in the pane, which you can drag into the text area.

2. Test your expression by completing the following actions:

1. Click Test.

2. In the Test data panel, enter input values for the properties that are referenced in the
expression.

3. Test either the entire expression or a fragment.

Complete one of the following actions:

To test the entire expression, click an area other than a field to move your focus.

The result of the test is displayed in the Result field that appears above the text editor.

Test a portion of the expression by selecting a fragment.

The result of the test is displayed in the Result of selection field that appears above the
text editor.
 3. Click Submit.

Expressions

An expression is a single text element that when produces a string value. Users create both SQL
expressions (or functions) for use in report definitions and Java expressions for use in activities and
other rules.

Examples of expressions

Expressions provide a wide range of computations. Some examples of expressions are:

Expressions
An expression is a single text element that when produces a string value. Users create both SQL
expressions (or functions) for use in report definitions and Java expressions for use in activities and other
rules.

For information about SQL functions, see Report Definitions — Using the Calculation Builder.

The information in this topic discusses creating Java expressions.

Expressions in Pega Platform look similar to formulas in Microsoft Excel but are based on Java language
conventions.

You can type in an expression, or (in many places) use the Expression Builder to guide you in entering an
expression. Expressions can include constants, property references, operators for arithmetic and logical
operations, parentheses to control the order of evaluation, and functions.

Expressions can perform operations on data, including:

Performing mathematical operations

Comparing property values
Manipulating text
Transforming data
Converting data types (casting)

Note: Expressions, which are used in many situations , differ from Declare Expression rules, which create
expressions that are evaluated automatically. Declare Expression rules contain expressions, but so do
many other rule types.

Expressions in rule forms

You can enter expressions in activities, data transforms, Constraints rules, and most other places that
compute a value at runtime.

In rule forms, the sorts of expressions you can enter into fields in the forms depends on the defined
behaviors of the rule form's fields and what sorts of entries they allow. The field in which an expression
appears determines whether the expression is part of:

The right-hand side of an assignment to a property

The computation of a value
A Boolean (or logical) expression (yielding a true/false value)
A property reference containing an expression as a subscript

You can also use expressions in most fields that allow a constant value. Similarly, you can use expressions
to supply the subscript value of a list or group element within a property reference.

You cannot use expressions in fields that require property references as the destination of assigning a
value. For example, you cannot use an expression in the Target column of a Set action in a data transform
or in the Property-Set method parameter array.

Expressions in HTML and XML streams

Through the <when> JSP tag and Java scriptlets (or the <when> directive and Java directive), you can
include expressions in HTML-based rules or XML Stream rules. You can use these in HTML rules, XML
Stream rules ( Rule-Obj-XML rule type) and correspondence rules ( Rule-Obj-Corr rule type).

Building expressions with the Expression Builder

Examples of expressions

Examples of expressions
Expressions provide a wide range of computations. Some examples of expressions are:

Constants

An expression can be as simple as a single literal constant. See Constants in Expressions for more
information.

"Good Evening"
142
true
20050705
0x143F871A

Single property references

An expression can reference a single property, identifying the page on which it is found. In the context of
an activity, an expression can reference a parameter or local variable.

.Price
parameters
MortgageLoan.Application.ZIPCode
primary.pyLabel

Aggregate property references

You can identify aggregate properties or parts of aggregate properties. (The property mode of the target
must match the result of the expression.)

MortgageLoan.Application.Address(4)
Globe.Division(7).Unit("West")
Invoices.pyOrders(2).pyItems("Manuals").pyItemNames

Linked property references

You can identify properties accessed through linked properties, using the syntax .property1.property2., where
property1 is the linked property and property2 is a property reference in the linked class.

Note: Note the initial period character before the property name. (When no initial period is present, the
system assumes that property1 is a page name.)
.pyUpdateOperator.pyLabel
.pyUpdateOperator.pySkillsPrimary(6)

Arithmetic, logical, and comparison operators

You can use most Java operators for arithmetic, string operations, comparisons, and conditions. Use
parentheses to control the order of evaluation.

.Price * (1+(.Tax/100)) + ShipInfoPage.ShippingCost

.pyEffortActual >= .pyEffortForecast
3.14159*.radius *.radius

Function calls

Your expressions can call built-in functions, functions in standard libraries, and custom functions.

@SUM(.SubComponents().Price)
@Pega-RULES:MapTo.Function(argument1, argument2)

All combined
Expressions can incorporate all the elements described in this topic together:

@SUM(.SubComponents(38+.Offset).Price)

Expressions

Configuring continuous integration and continuous deployment

Incorporate the effects of work of your development teams by implementing continuous integration and
deployment. Additionally, to speed application development and minimize the risk of conflicts, you can
provide separate sandboxes in which developers can work on multiple features simultaneously.

Branched application development

Your teams can develop multiple features simultaneously without overwriting work and causing
conflicts by implementing branched application development. During branched development,
developers can make changes in one ruleset that affect other developers only after you merge the
changes into a target ruleset. As a result, you speed up application development and can clearly
analyze what changes your application includes.

Creating a toggle

To enable or disable functionality that is under development, or to control access to a feature, create a
toggle. When you create a toggle, a when rule for the toggle instance is created by default.

Optimizing application load time

Improve the performance of your application by reducing content that is difficult to render. By running
preflight optimization, you eliminate unnecessary static content and improve load times, which
creates a better user experience.

Improving your compliance score

Follow development best practices to improve your compliance score. By eliminating risks, such as
custom code or degraded performance, you can improve quality and resolve issues before your
application goes into production.

Unit testing individual rules

An incorrect rule configuration in an application can cause delays in case processing. To avoid
configuration errors such as incorrectly routed assignments, unit test individual rules as you develop
them. To expedite future rules testing, you can create reusable test cases from the unit test.

Branched application development

Your teams can develop multiple features simultaneously without overwriting work and causing conflicts by
implementing branched application development. During branched development, developers can make
changes in one ruleset that affect other developers only after you merge the changes into a target ruleset.
As a result, you speed up application development and can clearly analyze what changes your application
includes.

For relevant training materials, see the Team application development module on Pega Academy

For example, by using branches, two teams can work simultaneously on different application features, such
as case type creation and notifications. Each team can make can make changes that do not affect the
changes of the other team during the development process, even if the features use the same base
rulesets. When the development process is complete, you can review branches to resolve any conflicts, and
then merge the results into a target ruleset in order to make the new features available in the final version
of your application.

To learn more about branched application development, see the following articles:

Branches and branch rulesets

Branches help you manage work in development environments in which multiple teams contribute to
a single application. You use branches to develop software simultaneously in a version-controlled
 environment. For example, a team can develop a feature in one branch while another team develops
another feature in a different branch, even if the teams share the same rulesets.

Implementing branched application development

For faster delivery of your products, configure your application development to use branches. By
implementing branches, team members can work simultaneously on multiple features, without the risk
of interrupting work of different team members.

Branch operations

After you create branches and develop rules in branch rulesets, you can work with branches in a
number of ways. For example, you can create branch reviews with other users, delete branches form
the system, and lock branches before you merge them.

Unit testing individual rules

Troubleshooting tools and techniques

Branches and branch rulesets

Branches help you manage work in development environments in which multiple teams contribute to a
single application. You use branches to develop software simultaneously in a version-controlled
environment. For example, a team can develop a feature in one branch while another team develops
another feature in a different branch, even if the teams share the same rulesets.

When you use branches, different development teams can work without interfering with changes that other
teams make in an application, even if multiple teams share one base ruleset. For example, Team A can
develop service-level agreements for a case type while Team B fixes UI bugs in the application. When you
provide separate branches for both teams, you minimize the risk of errors and work overwrites that might
arise when both teams work on the same ruleset simultaneously.

To organize rules better during your development process, you can categorize rules into branch rulesets.
Branch rulesets have the following characteristics:

Branch rulesets are branched from rulesets in your application.

Branch rulesets contain rules that are in active development in an associated branch.
Branch rulesets have a naming convention that includes a ruleset ID, the word Branch, and a branch
name, for example, SLAS_Branch_TeamABranch, where SLAS is a ruleset ID, Branch indicates a branch ruleset,
and TeamABranch is a branch name.

Branching is especially useful in large development projects when multiple teams work simultaneously on
the rules in an application, and members of one team view each others work, but isolate their development
changes from other teams. Consequently, rule changes that one team makes do not affect the other teams
until the changes are stable, conflicts are resolved, and the approval is granted to make the new
improvements available to the entire development project team.

Branched development includes the following main tasks:

1. You create a development application that your team can use to develop new features. You create a
development application by copying an existing application to ensure that the names of classes and
rulesets remain unchanged.

For more information, see Creating a development application.

2. You add development branches to the development application. Teams use branches to develop
features independently.

For more information, see Adding development branches to your application.

3. As a best practice, you create a branch review to ensure that rules in your branches are guardrail-
compliant and meet your business objectives.

For more information, see Branch reviews.

4. You make new features available in your application by merging changes from branches into a target
ruleset. You now can resolve conflicts and address warnings that might arise among different
 branched versions of the same ruleset.

For more information, see Merging branches into target rulesets.

For example: The following figure shows a sample scenario in which multiple development teams create
service-level agreements (SLAs) and resolve UI bugs in a Loan Requests application. An administrator
creates two development applications: one for the UI teams and one for the SLAs teams. In each
application, the administrator creates two branches that contain branch rulesets. As a result, two teams
can resolve UI bugs and two teams can develop SLA rules without affecting another team. After the
development is complete, the administrator first reviews and then merges branches into target rulesets. As
a result, the Loan Requests application includes new features from the simultaneous work of four
development teams.

Branched development

Branches and unlocked rulesets

An alternative to branched development is working in unlocked rulesets. Unlocked rulesets are suitable for
projects that typically involve one team, and team members immediately need to view changes that any
team members make. When a developer saves a change in an unlocked ruleset, the change immediately
affects the work of other developers on that application.

During branched application development, a change that a developer makes in a branch ruleset affects the
work that other developers do on the same development application only after merging changes into a
target ruleset.
For relevant training materials, see the Team application development module on Pega Academy

Adding development branches to your application

Troubleshooting tools and techniques

Implementing branched application development

For faster delivery of your products, configure your application development to use branches. By
implementing branches, team members can work simultaneously on multiple features, without the risk of
interrupting work of different team members.

For example, team members can develop different service-level agreement rules or work on multiple bugs
in parallel by using separate branches.
To use branches in your application, create a development application that is built on your base
application. You create and save rules in your development application, which results in creating branch
rulesets. You can then work with branches in several ways, such as creating branch reviews and merging
branches.

To configure your application to use branches and branch rulesets, complete the following steps:

1. Create a development application that is built on your base application.

For more information, see Creating a development application.
2. Add branches to your application, into which you can save the rules that you develop.
For more information, see Adding development branches to your application.
3. Work with branches in several ways that meet your business requirements. For example, create a
review, merge branches, or delete branches from the system.
For more information, see Branch operations.

Creating a development application

To speed up application development, you can support branched development by creating a

development application that is built on the production application. By providing branches for
development, you ensure that different teams and team members can work on different features
simultaneously, without a risk of creating errors and conflicts.

Adding development branches to your application

To avoid conflicts and errors when team members work simultaneously, add development branches to
your application so that team members can work simultaneously on multiple features without risking
conflicts and errors that can arise from working on the same rules.

Adding system branches

You can add branches that already exist on your system to your application. You cannot add a branch
that contains branched versions of a ruleset that is not in your application stack.

Creating branch rulesets

Provide your development team with an ability to work on multiple features in parallel by creating
branch rulesets. When you save rulesest in different branches, team members can work on isolated
rulesets without impacting development of other features. As a result, you avoid overwriting results
and generating errors.

Setting branch development preferences

Branches and branch rulesets

Creating a development application

To speed up application development, you can support branched development by creating a development
application that is built on the production application. By providing branches for development, you ensure
that different teams and team members can work on different features simultaneously, without a risk of
creating errors and conflicts.

For example, different team members can work on bug fixes that correspond with two separate features
but refer to the same base rule. During development, conflicts might occur. Edits made by one team
member might impact the work of other developers. Creating a development application is not mandatory
but can provide an uninterrupted development process, especially for large or multiple development teams
that work on the same application.
For branched development, create a new application by copying an existing application. As a result, the
names of classes and rulesets remain unchanged. Consequently, you can conveniently merge your changes
after the development in a branch is complete.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. In the rule form header, click the Down arrow next to the Save button, and then click Save as.
3. In the Application Record Configuration section, in the Label field, enter a name of your
development application.
Team application names typically reflect the base application and team name or the focus of the team.
For example: For a base MyBankingApp application, the development team that works on the layout
of the user portal can name the development application MyBankingAppPortal.
4. Create a unique application rule by changing the identifier:
a. In the Identifier section, click Edit.
b. In the dialog box that is displayed, in the text field, enter a new identifier.
c. Click OK.
5. Optional: To create another version of a development application that already exists, in the Version
field, enter a new version number.
6. In the Context section, in the Add to ruleset list, select a ruleset to store your edits.
The ruleset that the system prompts by default is the ruleset in your production application. If you
select a different ruleset, you are unable to add your changes directly to the production application.
7. Click Create and open .

What to do next:

In your development application, add the main application as a built-on application. For more
information, see Adding built-on applications.
Provide access to your application for development team members. For more information, see
Learning about access groups.

Building your first application

Adding development branches to your application

To avoid conflicts and errors when team members work simultaneously, add development branches to your
application so that team members can work simultaneously on multiple features without risking conflicts
and errors that can arise from working on the same rules.

For example, one team member can fix bugs in the application UI while another developer fixes invalid
service-level agreement rules. If both rules refer to the same base rule, working in separate branches
prevents conflicts during development.

1. In the header of Dev Studio, click the name of the application, and then click Definition.
2. In the Development branches section, click Add branch.
You can add branches that contain rulesets only from your current application.
3. In the Add a Branch ID dialog box, in the Branch name field, enter a branch name:
To create a new branch, enter a unique name that starts with a letter.

Ensure that the branch name reflects the purpose so that your development team can easily
identify the correct branch in which to save changes during application development.

To reuse an existing branch from your system, press the Down arrow key, and then select a
branch that you want to use.
4. Click Submit.
5. Optional: If you have multiple branches, you can specify how the system selects the rules for rule
resolution by reordering the list of branches.
For more information, see Reordering branches.

The system selects the rules from the top branches first.

6. Optional: If you use Live UI, to facilitate application development so that less technical users can
modify common properties of a control or the layout of rules in the branch, set up and manage a run-
time branch.
 For more information, see Enabling run-time branching and editing.
7. Create rules and add them to your branch.
The system automatically creates rulesets where you save your rules. For more information about
working with rules in branches, see Rule development in branches.

Result: When you develop your application, you can select the branch and ruleset into which you want to
save new rules.

Rule development in branches

To add rules to branches, when you create a rule, you can select the branch where you want to save
your rule. Branch rulesets are automatically created.

Branch operations

Rule development in branches

To add rules to branches, when you create a rule, you can select the branch where you want to save your
rule. Branch rulesets are automatically created.

Working with rules in the branch ruleset is the same as in standard rulesets, except for the following
differences:

Final rules – You can typically modify final rules only in the ruleset and class in which they are
declared final. This limitation means you cannot normally copy final rules to another ruleset that either
has the same Applies To class or is located within the subclass of the ruleset of the final rule. For
branch rulesets that are branched from the originating ruleset of the final rule, this limitation is
removed. You can check out a final rule from its original ruleset into a branch ruleset that is branched
from the owning ruleset. For more information, see Checking out a rule to a branch.
Utility functions – Some function references in the system use the ruleset name as part of the
reference. To allow for rules to appropriately reference functions that exist in rules in a branch ruleset,
the system's function lookup considers the branches in your ruleset list when resolving the references.

Developing branches with libraries and functions

Libraries hold custom functions for your application, which can supplant and extend standard
functions. For example, the OperatorHasPrivilege function verifies that a user has a specific privilege.

Branch operations

Developing branches with libraries and functions

Libraries hold custom functions for your application, which can supplant and extend standard functions. For
example, the OperatorHasPrivilege function verifies that a user has a specific privilege.

However, you cannot create libraries in branch rulesets. Libraries are based on the ruleset name only, not
the ruleset version. Because you must merge branches into a particular ruleset version, you cannot create
libraries directly in branch rulesets.

To use libraries and functions in branches, perform the following steps:

1. Create a library and save it in the base ruleset.

2. Create the functions that the library contains and save them into a branch ruleset.
3. Merge the branch so that libraries and functions are contained within the branch.

Rule development in branches

Merging branches into target rulesets

Adding system branches

You can add branches that already exist on your system to your application. You cannot add a branch that
contains branched versions of a ruleset that is not in your application stack.

1. In the navigation panel, click App, and then click Branches.

2. Right-click the application to which you want to add a system branch and select Add branch from
 this system.
3. Press the Down Arrow and select the system branch that you want to add.
4. Click Submit.
5. If you are using multiple branches, reorder the list of branches so that it matches the order in which
rules should be resolved.
For more information, see Reordering branches.
6. Create rules and add them to your branch.
When you create rules, you can select the branch and ruleset into which you want to save them.
Rulesets are automatically created. For more information, see Rule development in branches.

Adding development branches to your application

Creating branch rulesets

Provide your development team with an ability to work on multiple features in parallel by creating branch
rulesets. When you save rulesest in different branches, team members can work on isolated rulesets
without impacting development of other features. As a result, you avoid overwriting results and generating
errors.

Before you begin: Enable branch development. For more information, see Branches and branch rulesets.

1. In the header of Dev Studio, click Create SysAdmin RuleSet .

2. Create a new ruleset or a ruleset version:
To create a new ruleset, in the RuleSet Name field, enter a unique name for your ruleset.
To create a new ruleset version, in the RuleSet Name field, press the Down arrow key, and then
select the ruleset for which you want to create a new version.
Result: The system autopopulates the version and description of your ruleset.
3. Select the Branch RuleSet check box.
4. In the Branch ID list, select a branch to store your ruleset.
5. In the Ruleset to branch list, select a ruleset that you want to branch.
6. Click Create and open .

Result: The system creates a new ruleset version and saves it in the branch.What to do next: Configure
version settings for the ruleset. For more information, see Configuring ruleset version settings.

Adding development branches to your application

Branch operations
After you create branches and develop rules in branch rulesets, you can work with branches in a number of
ways. For example, you can create branch reviews with other users, delete branches form the system, and
lock branches before you merge them.

Setting branch development preferences

Define branches where you want to save the changes that you make in App Studio, so that you can
work on a feature without affecting other parts of your application.

Viewing branch quality and branch contents

You can view information about your branch, such as the rules that it contains and whether branches
have been reviewed. You can also view quality metrics such as guardrail warnings for information
about the health of your branch.

Reordering branches

If you use multiple branches in your application, ensure that the order of the branches in the
application rule form matches the order in which rules should be resolved for this application.

Locking a branch

Before you merge a branch, lock the branch after development is complete so that no further
modifications can be made to the rulesets within the branch. When you lock a branch, all rulesets
within the branch are locked.
 Packaging a branch

To retain a copy of your branch, you can package the contents of a branch in a .jar file. Data instances
that are tagged with the rulesets that are associated with the branch and history record are included
in the package.

Removing a branch from an application

When you remove a branch, you remove an association between a branch and an application.
Removed branches and their rulesets are not available when you create or copy records in the
application.

Deleting a branch from the system

You can delete an entire branch and its contents from the system. You can also package the branch in
a JAR file and download it before deleting it.

Branch reviews

To increase the quality of your application, you can create reviews of branch contents to improve
branch quality by, for example, ensuring that the rules are guardrail-compliant. You can assign branch
reviews to other users, use Pulse to collaborate on reviews, and close reviews after you have
addressed any issues.

Merging branches into target rulesets

When rule development in a branch is complete, make the changes available by merging branches
into a target ruleset of the development application. As a result, your team provides required solutions
in a timely and efficient way, without the risk of overriding or losing work.

Branches and branch rulesets

Integrating with file and content management systems

Setting branch development preferences

Define branches where you want to save the changes that you make in App Studio, so that you can work on
a feature without affecting other parts of your application.

For example, you can create a sandbox branch where you can develop and test different rules, and then
merge or discard your changes. You can also create multiple branches to work on different features or bugs
within one application.

1. In the header of App Studio, click the Toggle branch development icon.
2. In the Branch development preferences dialog box, toggle the branch development on.
3. Optional: From the list, select an application layer where you want to make changes.
4. Define the branch to save your changes:
From the list, select a branch.
If you need a new branch, click Create a new branch, and then complete the dialog box.
5. Click Submit.
By default, Dev Studio sets the context of new and updated rules to the highest branch in your
application.

Rule development in branches

Viewing branch quality and branch contents

You can view information about your branch, such as the rules that it contains and whether branches have
been reviewed. You can also view quality metrics such as guardrail warnings for information about the
health of your branch.

1. In the Dev Studio navigation pane, click App, and then click Branches.
2. Click a branch, and then click the Content tab to view the rules that the branch contains.
You can also see if a branch has been reviewed and can open a review in the branch.
3. Click the Branch quality tab to view guardrails, merge conflicts, and information about the unit tests
that are configured on the rules in the branch.
 Understanding branch quality metrics

You can view quality metrics to monitor the health of your branch.

Branches and branch rulesets

Understanding unit test cases
Understanding branch quality metrics

Understanding branch quality metrics

You can view quality metrics to monitor the health of your branch.

Branch quality metrics include the following information:

Guardrails
Monitor the number and severity of guardrail violations that were found in your branch. By investigating
and resolving the violations, you can improve your branch's overall quality.

The Guardrails section displays the following information:

Weighted score: The score calculated by comparing guardrail warnings (weighted by severity and
justification) against the total number of rules in the branch.
Warnings: The total number of guardrail warnings in the branch.
Severe: The number of severe guardrail warnings in the branch.

For more details about individual guardrail violations, select the Warnings tab.

Test coverage
Check how many of your branch rules are covered by tests of any kind.

The Test coverage section displays the following information:

Rules covered: The percentage of the branch rules covered by tests.

For more details about individual rules, select the Uncovered rules tab.

Unit testing
Monitor unit test results and see how many of your branch rules have unit test cases written for them.

The Unit testing section displays the following information:

Rules with unit tests: The percentage of the branch rules with unit tests.
Test pass rate: The percentage of unit tests written for the branch rules that passed.

For more details, select the Failed unit tests and Rules without unit tests tabs.

Merge conflicts
Investigate any potential merge conflicts to identify problems with your branch as early as possible.

The Merge conflicts tab displays the following information:

Total: The total number of potential merge conflicts between the branch and the main application.
Name: The name of a rule that is causing a potential merge conflict.
Rule type: The type of rule that is causing a potential merge conflict.
Base rule: The fallback rule that is selected by the conflicted rule's resolution.

Warnings
Investigate individual guardrail violation warnings to identify problems related to your branch.
The Warnings tab displays the following information:

Total: The total number of guardrail warnings in the branch.

Severe: The number of severe guardrail warnings in the branch.
Moderate: The number of moderate guardrail warnings in the branch.
Rule name: The name of a rule that is causing a guardrail warning.
Rule type: The type of rule that is causing the guardrail warning.
Ruleset: The ruleset that contains the rule that is causing a guardrail warning.
Severity: The severity status of the guardrail warning.
Warning type: The type of the guardrail warning.
Justified: The justification status of the guardrail warning.
Warning message: The guardrail warning message.
Introduced by: The user who introduced the rule that is causing the guardrail warning.

Uncovered rules
Investigate individual rules that are still uncovered by tests of any kind.

The Uncovered rules tab displays the following information:

Executable rules: The total number of executable rules in the branch.

Uncovered rules: The number of branch rules that are not covered by tests.
Rule name: The name of a rule that is not covered by unit tests.
Rule type: The type of rule that is not covered by unit tests.
Class: The class of the rule that is not covered by unit tests.
Ruleset: The ruleset that contains the rule not covered by unit tests.

Failed unit tests

Determine the causes of individual unit test failures.

The Failed unit tests tab displays the following information:

Total unit tests: The total number of unit tests in the branch.
Failed unit tests: The number of failed unit tests in the branch.
Test case name : The name of a failed unit test case.
Rule type: The type of rule that failed the unit test case.
Rule name: The name of the rule that failed the unit test case.
Class: The class of the rule that failed the unit test case.
Last run: The time when the failed unit test case was last run.
Result: The result of the failed unit test case.
Run history: The run history of the failed unit test case.

Rules without unit tests

Investigate the details of rules that are supported by unit testing but that still do not have unit test cases
written for them.

The Rules without unit tests tab displays the following information:

Supported rules: The number of branch rules that are supported by unit tests.
Rules without unit tests: The number of supported rules without unit tests.
Rule name: The name of the rule without a unit test.
Rule type: The type of rule without a unit test.
Ruleset: The ruleset that contains the rule without a unit test.

Viewing branch quality and branch contents

Justifying an application warning
Base rules

Reordering branches
If you use multiple branches in your application, ensure that the order of the branches in the application
rule form matches the order in which rules should be resolved for this application.

1. To open the application rule form, click the application name in the Dev Studio header, and then click
Definition.
2. On the Definition tab, in the Development branches branches section, drag a branch to move it.
When you log in to this application, the system assembles the ruleset list and branch rulesets
according to the sequence in which the branches are listed.
3. Optional: If you are using Live UI, you can set up and manage a run-time branch so that less
technical users can modify common properties of a control or a layout on rules in the branch. See
Enabling run-time branching and editing for more information.
4. Click Save.

Adding development branches to your application

Branches and branch rulesets

Locking a branch
Before you merge a branch, lock the branch after development is complete so that no further modifications
can be made to the rulesets within the branch. When you lock a branch, all rulesets within the branch are
locked.

1. Check in any rules that are checked out. You cannot lock a branch if any rules are checked out.
2. In the navigation panel, click App, and then click Branches.
3. Right-click the branch that you want to lock and select Lock.
4. Enter a password to lock the branch.
5. Reenter the password to confirm it.
6. Click Lock.

Branches and branch rulesets

Packaging a branch
To retain a copy of your branch, you can package the contents of a branch in a .jar file. Data instances that
are tagged with the rulesets that are associated with the branch and history record are included in the
package.

1. In the navigation panel, click App, and then click Branches.

2. Right-click the branch that you want to package and click Package. A browser window displays the
progress of the packaging process.
3. Click the link in the browser window to save the .jar file to a local directory. If any rules in the branch
rulesets are checked out, the latest version of the checked-in rule is included in the package.

Branches and branch rulesets

Removing a branch from an application

When you remove a branch, you remove an association between a branch and an application. Removed
branches and their rulesets are not available when you create or copy records in the application.

Note: Removing a branch does not delete its contents from the system. To delete a branch from the
system, see Deleting a branch from the system.

1. In the navigation panel, click App, and then click Branches.

2. Right-click the branch that you want to remove from your application and click Remove from
application.

Branches and branch rulesets

Deleting a branch from the system

You can delete an entire branch and its contents from the system. You can also package the branch in a
JAR file and download it before deleting it.

1. Check in any records that are checked out.

 2. In the navigation panel, click App, and then click Branches.
3. Click the branch that you want to delete.
4. Click App Delete from system .
5. Optional: If there are rulesets in the branch, and you want to save them in a JAR file that you can
download, select the Save branch contents in a JAR fie for download check box.
6. Click Delete in the confirmation dialog box.
7. Click Done.

Branches and branch rulesets

Branch reviews
To increase the quality of your application, you can create reviews of branch contents to improve branch
quality by, for example, ensuring that the rules are guardrail-compliant. You can assign branch reviews to
other users, use Pulse to collaborate on reviews, and close reviews after you have addressed any issues.

If you have a Default email account configured, you are notified when reviews are assigned to you and
when reviews are closed. For more information, see Creating an email account in Dev Studio.

If Pulse notifications are configured, you can receive emails when a new comment is added or when a reply
is posted to a new comment. For more information, see Configuring Pulse email notifications.

You can override the following when rules to allow merges when branches are unlocked or not reviewed:

pyAllowMergeWhenNotReviewed: Override to disallow merges when branches have not been

reviewed.
pyAllowMergeWhenUnlocked: Override to disallow merges when branches are not locked.

Creating a branch review

You can create a review for a branch so that you and other review team members can collaborate to
improve the branch quality before you merge the branch. Only one branch review can be open at a
time.

Modifying a branch review

For open branch reviews, you can modify the list of users who are assigned to the review.

Deleting a branch review

You can delete both open and closed branch reviews.

Closing a branch review

You can close a branch review after all comments have been addressed.

Reopening a branch review

You can reopen a branch review after the review was closed, for example, if a reviewer inadvertently
closed it.

Reviewing branches

If you are a branch reviewer, you can open reviews and inspect the rules within the branch improve
the quality of the branch, for example, before you merge its contents. You can also communicate with
other users in Pulse to work collaboratively on branch reviews.

Branches and branch rulesets

Creating a branch review

You can create a review for a branch so that you and other review team members can collaborate to
improve the branch quality before you merge the branch. Only one branch review can be open at a time.
If you have a Default email account configured, you are notified when reviews are assigned to you and
when reviews are closed. For more information, see Creating an email account in Dev Studio.

Complete the following steps:

1. As a best practice, check in any rules that are checked out.

2. In the navigation panel, click App, and then click Branches.
3. Click the branch for which you want to create the review.
4. On the Content tab, click Create review.
5. In the Create Review dialog box, in the Objective field, enter the purpose of the review.
6. In the Due field, specify the date on which the review should be completed.
7. In the User ID field, press the Down Arrow and select the user ID of a reviewer.
8. Add more reviewers by clicking the Plus sign and repeating the previous step.
9. Click Create.

Branch reviews
Branches and branch rulesets

Modifying a branch review

For open branch reviews, you can modify the list of users who are assigned to the review.

1. In the navigation panel, click App, and then click Branches.

2. Click the branch for which you want to modify the branch review.
3. On the Content tab, in the Current review section, click the review to open it.
4. Select Actions Manage review team .
5. Add or remove reviewers, as appropriate.
6. Click OK.

Branch reviews
Branches and branch rulesets

Deleting a branch review

You can delete both open and closed branch reviews.

1. In the navigation panel, click App, and then click Branches.

2. Click the branch for which you want to delete the review.
3. On the Content tab, in the Current reviews section, click the review to open it.
4. Click Actions Delete .

Branch reviews
Branches and branch rulesets

Closing a branch review

You can close a branch review after all comments have been addressed.

If you have a Default email account configured, you are notified when reviews are assigned to you and
when reviews are closed. For more information, see Creating an email account in Dev Studio.

Complete the following steps:

1. In the navigation panel, click App, and then click Branches.

2. Click the branch for which you want to close the review.
3. On the Content tab, in the Current review section, click the review to open it.
4. Click Actions > Close.
5. A dialog box is displayed if branches in the rule are checked out. Click Yes to close the review.
6. Click Submit.

Branch reviews
Branches and branch rulesets

Reopening a branch review

You can reopen a branch review after the review was closed, for example, if a reviewer inadvertently closed
it.

1. In the navigation panel, click App, and then click Branches.

2. Click the branch for which you want to reopen the branch review.
3. On the Content tab, in the Previous reviews section, click the review to open it.
4. Select Actions Reopen .
5. In the dialog box, click Yes to confirm that you want to reopen the review.

Branch reviews
Branches and branch rulesets

Reviewing branches
If you are a branch reviewer, you can open reviews and inspect the rules within the branch improve the
quality of the branch, for example, before you merge its contents. You can also communicate with other
users in Pulse to work collaboratively on branch reviews.

If you have a Default email account configured, you are notified when a review is assigned to you and when
reviews are closed. For more information, see Creating an email account in Dev Studio. If Pulse notifications
are configured, you can receive emails when a new comment is added or when a reply is posted to a new
comment. For more information, see Configuring Pulse email notifications. Complete the following steps:

1. In the navigation panel, click App, and then click Branches.

2. Click the branch that has the review that you want to open.
3. On the Content tab, in the Current review section, click the review to open it. You can perform the
following actions:
Filter the list of rules in the branch by rule type using the drop-down list.
Click General comments to post and view Pulse comments about the branch.
Click a rule to collaborate with other users in Pulse about the specific rule. You can open the rule
form on this page.

Branch reviews
Branches and branch rulesets

Merging branches into target rulesets

When rule development in a branch is complete, make the changes available by merging branches into a
target ruleset of the development application. As a result, your team provides required solutions in a timely
and efficient way, without the risk of overriding or losing work.

Before you begin: Check all rules into their base rulesets before you merge branches. For more
information, see Checking in a rule.

As a best practice, the system administrator creates a new ruleset version for the base ruleset,
independent of the wizard. Individual teams develop rules in their specific branches, and then merge those
branches into the existing base ruleset version that the administrator provides. As a result, administrators
have better control over versions.

For relevant training materials, see the Merging a development branch challenge on Pega Academy

1. Optional: To save time and resolve any potential issues before merging rulesets, check whether any
conflicts might occur.
For more information, see Viewing branch information.
2. Optional: To ensure that branches include only changes that you want to merge, lock a branch after
development is complete.
For more information, see Locking a branch.
3. In the navigation pane of Dev Studio, click App.
4. In the App Explorer, click the Branches tab.
5. Select branches that you want to merge:
Choices Actions

Merge a single a. Right-click the branch, and then click Merge.

branch b. In the Merge branch dialog box, click Proceed.
 Choices a. Right-click your applicationActions
name, and then click Merge multiple
branches.
Merge multiple
b. In the Select Branches to Merge dialog box, select the branches that
branches
you want to use.
c. Click OK.
6. If conflicts or warnings occur, on the Merge Branches tab, review information about any issues.
You must resolve conflicts before you can merge branches. For more information, see Conflicts and
warnings in the Merge Branches wizard.
7. In the Target ruleset section, in the list of versions, select the base ruleset version into which you
want to merge rulesets:
To create a new ruleset version in the base ruleset during the merge, select Create new
version.
To reuse an existing ruleset, select the ruleset version.
8. Click Merge. Result: When a merge is complete, you can view the details about the outcome, the
number of merged rules, and the source and target rulesets.

Conflicts and warnings in the Merge Branches wizard

The Conflicts and Warnings window displays an expandable list of rules that the Merge Branches
wizard has identified as having conflicts, warnings, or both. To open this window, click the displayed
number of conflicts and warnings on the main wizard screen.

Branch merge process customization

You can enhance the merge process for your development team in various ways to comply with your
organization's policies and procedures. By using extension points, you customize the standard branch
merge process. For example, you can add postprocessing behavior that sends an email notification to
the project lead with the status of the merge process.

Branches and branch rulesets

Conflicts and warnings in the Merge Branches wizard

The Conflicts and Warnings window displays an expandable list of rules that the Merge Branches wizard has
identified as having conflicts, warnings, or both. To open this window, click the displayed number of
conflicts and warnings on the main wizard screen.

Note: The displayed report of conflicts and warnings depends on the target ruleset version selected for the
merge. For example, merging a rule into target ruleset version 01-01-01 might display no conflicts and one
warning, while merging that rule into target ruleset version 01-01-02 might display one conflict and no
warnings. You must select the target ruleset version for the merge to get an accurate report of the potential
conflicts and warnings.

When there are resolved conflicts, the report refreshes to indicate how many are resolved.

Conflicts in the Merge Branches wizard

Before the wizard proceeds with the merge, you must indicate in this window that you have resolved
all conflicts reported by the wizard. Conflicts occur for the following situations:

Resolving conflicts in the Merge Branches wizard

To resolve the conflicts for a rule, complete the following steps:

Addressing warnings in the Merge Branches wizard

Warnings are primarily informational and are provided to make you aware of how merging your branch
might impact other teams or might not behave exactly as you think it will.

Merging branches into target rulesets

Conflicts in the Merge Branches wizard

Before the wizard proceeds with the merge, you must indicate in this window that you have resolved all
conflicts reported by the wizard. Conflicts occur for the following situations:
 Conflict
Example of how this occurs
situation

Base ruleset XYZ has two locked ruleset versions, 01-01-01 and 01-01-02. TeamA
The rule in a
branches XYZ into their Story-A branch, and TeamB branches XYZ into their BugFix-1
lower base
branch. TeamB's work is a bug fix for version 01-01-01, and they complete their work
ruleset
and merge their BugFix-1 branch with the changed rules for base ruleset XYZ into 01-01-
version has
01. Then TeamA starts the wizard to merge their Story-A branch by creating a new
been recently
version for base ruleset XYZ. The wizard reports a conflict because the rule was updated
updated.
in ruleset version 01-01-01 (a lower version) by TeamB prior to TeamA's merge.

The rule in the

Base ruleset XYZ has two locked ruleset versions, 01-01-01 and 01-01-02. TeamA
selected
branches XYZ into their Story-A branch, and TeamB branches XYZ into their Story-B
target (base)
branch. TeamB completes their work and merges their Story-B branch into 01-01-02.
ruleset
Then TeamA starts the wizard to merge their Story-A branch into 01-01-02 also. The
version has
wizard reports a conflict because the rule was updated in the same ruleset version 01-
been recently
01-02 (TeamA's selected target version) by TeamB prior to TeamA's merge.
updated.

The same rule

exists in Base ruleset XYZ has one version, 01-01-01. TeamA has branches Story-A and Story-B,
multiple which have the same rule. Story-A is the topmost branch in the hierarchy. Story-A and
branches that Story-B are being merged using multibranch merge.
are merged
using the The wizard reports a conflict for Story-A branch because Story-B has the same rule and
wizard to will be merged before Story-A. To resolve this conflict, move all your changes for this rule
merge from the Story-B branch to the rule in Story-A.
multiple
branches.

Resolving conflicts in the Merge Branches wizard

Conflicts and warnings in the Merge Branches wizard
Merging branches into target rulesets

Resolving conflicts in the Merge Branches wizard

To resolve the conflicts for a rule, complete the following steps:

1. Examine the conflicts reported for the rule in the Conflicts and Warnings window.
2. Click Compare next to the first conflict to examine the differences between your branch copy of the
rule and the one in the base ruleset. Alternatively, click the ruleset name to open the base rule and
directly examine it.
3. Review and resolve all of the differences between the base rule and your branch rule.
If the changes are minor (such as a typo), open your branch rule and apply the same changes to
it so that it matches the base rule.
If the changes are more complex, or if they conflict with the choices or logic in your branch rule,
contact the individual who modified the base rule and negotiate what the final set of changes
should be and the testing procedure for testing them. After reaching a mutual decision, make the
agreed-upon changes in your branch rule and test.
4. When changes to your branch rule are completed and tested, select the Mark as Resolved check box
to indicate you have resolved the conflict.

Result:

After all conflicts reported in the Conflicts and Warnings window are marked resolved, you can click OK
to close the window and return to the Merge Branches wizard to continue with the merge process.

In the main screen of the wizard, you can see if all conflicts are resolved by verifying if the number of
Resolved conflicts matches the number of reported conflicts for all of the branch rulesets.

Conflicts in the Merge Branches wizard

Comparing rule versions

Addressing warnings in the Merge Branches wizard

Warnings are primarily informational and are provided to make you aware of how merging your branch
might impact other teams or might not behave exactly as you think it will.

Warning
Example of how this occurs Recommended steps
situation

1. Click Compare next to the warning to

examine the differences between your branch
copy of the rule and the one in the other base
ruleset version. Alternatively, click the ruleset
name next to the caution icon to open the
other rule and directly examine it.
2. Review all differences between the rules, and
use the Related Rules display to assess the
impact of the differences.

If the features in the rule in the higher ruleset

A rule with version does not apply to your target ruleset
the same version, and your changes in the lower target
You are merging the branch rule
keys as the are not present in, or will not impact, the one
into target ruleset version 01-01-01,
branch rule in the higher ruleset version, it is likely safe
and the corresponding base rule
exists in a to proceed with your merge. Merge into the
also exists in target ruleset version
higher ruleset lower ruleset version. The changes in the rule
01-01-02.
version in the will work at that ruleset version level. Those
target ruleset. applications that use the higher ruleset
versions might not see your merged changes.

For changes in your branch rule that you

determine need to be ported to the rule in the
higher ruleset version, define a new
development application and matching
branch using the higher ruleset version, and
copy the base rule from the higher ruleset
version into that branch ruleset. Make your
changes in that branch, test, and merge to
the higher ruleset version.

1. Click Compare next to the warning to

examine the differences between your branch
copy of the rule and the one in the other
branch. Alternatively, click the ruleset name
next to the caution icon to open the other rule
The and directly examine it.
corresponding 2. Review all differences between the rules, and
base rule Another team has branched the use the Related Rules display to assess the
exists in same base ruleset that you are impact of the differences.
another merging, and has a copy of the base 3. Contact the owner of the other branch, or the
branch rule in their branch ruleset. author of the other branched rule, and
ruleset in the describe the changes you made to the rule in
system. your branch and how they can test for the
changes. Best practice is they would validate
your changes after your merge your branch
and they obtain your changes and include
them in their branch.
4. Complete the merge of your branch.

1. Click Compare next to the warning to

examine the differences between your branch
copy of the rule and the one in the other
branch. Alternatively, click the ruleset name
 Warning next to the caution icon to open the other rule
The Example of how this occurs Recommended steps it.
and directly examine
situation
corresponding 2. Review all differences between the rules, and
In this situation, the rule exists in
base rule use the Related Rules display to assess the
another branch ruleset which will
exists in impact of the differences.
later be merged into a different
another 3. Contact the owner of the other branch, or the
ruleset than the one the
branch author of the other branched rule, and
corresponding base rule is in. A
ruleset, which discuss why a rule with the same name exists
team has branched a base ruleset
is branched in two different rulesets, and determine
that is different than the one you are
from a whether there are reasons for both to exist or
merging, and has copied the base
different whether one should be removed.
rule that corresponds to your branch
ruleset than If the base rulesets are for different
rule into their branch ruleset.
your branch purposes and will not be run
ruleset. concurrently, then continue with your
merge.
If the teams agree the rulesets are to be
combined, negotiate an appropriate
conclusion and perform agreed-upon
changes. Depending on the outcome,
complete your merge if appropriate.

1. Click Compare next to the warning to

examine the differences between your branch
copy of the rule and other rule. Alternatively,
click the ruleset name next to the caution
icon to open the other rule and directly
examine it.
2. Review all differences between the rules, and
use the Related Rules display to assess the
impact of the differences.
A rule with
3. Contact the owner of the other ruleset, or the
the same
A rule exists in the system that has author of the other rule, and discuss why a
keys has been
the same keys as the rule you are rule with the same name exists in two
updated
merging, and the other rule has different rulesets, and determine whether
somewhere
been updated. there are reasons for both to exist or whether
else in the
one should be removed.
system.
If the base rulesets are for different
purposes and will not be run
concurrently, then continue with your
merge.
If the teams agree the rulesets are to be
combined, negotiate an appropriate
conclusion and perform agreed-upon
changes. Depending on the outcome,
complete your merge if appropriate.

Conflicts and warnings in the Merge Branches wizard

Branch merge process customization

You can enhance the merge process for your development team in various ways to comply with your
organization's policies and procedures. By using extension points, you customize the standard branch
merge process. For example, you can add postprocessing behavior that sends an email notification to the
project lead with the status of the merge process.

The merge process and its extension points

When development in a branch is complete and stable, you can use the Merge Branches wizard to merge
the changes in one or more branches to the base rulesets.Tip: As a best practice, use the customizable and
model-driven pipelines of Deployment Manager to validate a branch before a merge. For more information,
see Using Deployment Manager for model-driven DevOps and Start a Deployment Manager deployment in
a distributed, branch-based environment by using the Merge Branches wizard.

The merge process is defined by the standard flow rule pzMergeInstances in the PegaAccel-Management-
Refactor-Instances-Merge class.

pzMergeInstances process
For preprocessing and postprocessing behavior, the process has two extension points (as subprocesses), to
which you can add custom steps.

By saving a copy of the standard rule and customizing your copy, you can override the generic behavior.
For more information about making a copy of the standard rule, see the Creating a class to organize your
customizations section.

The standard merge process provides extension points, at which you can provide new behavior:

pyPreMergeInstances (subprocess)
To add preprocessing behavior. By customizing a copy of pyPreMergeInstances, you can provide
processing that occurs before the Merge Branches wizard starts, such as verifying that a user's
operator ID is performing the merge instead of a generic account ID.
pyPostMergeInstances (subprocess)
To add postprocessing behavior. By customizing a copy of pyPostMergeInstances, you can provide
processing that occurs after the Merge Branches wizard completes, such as sending an email notifying
the team about the status of the merge.
pyValidateMergeOptions (activity)
To customize validation on the inputs into the user interface of the Merge Branches wizard.

You can also modify the UI for the merge process by overriding the following sections and when rules in the
Merge Branches wizard:

pyMergeInstancesRuleSetListFooter (section)
To customize the pre-merge screen by adding fields or information to the bottom of the merge wizard.
pyConfirmContent (section)
To customize the confirmation screen. You can modify this section to show a message to the user after
the user submits the merge or when a user returns the merge work object to review.
pyRestrictedTargetOptions (when rule)
To apply custom logic for merge options, such as Hide Merge Options, which determines which target
rulesets and passwords are visible.
pyMergeButtonDisabled (when rule)
To apply custom logic for when the merge is enabled on the UI, such as the Disable Merge Button
option.

Creating a class to organize your customizations

The recommended action before extending the merge wizard is to create a class to store all your
extensions. By creating a class to add your customizations, you can expose different merge behaviors and
enable users to fall back to an existing behavior.

Tip: You can create a new component to expose your merge wizard customizations, which provides a way
to package and share your customization between different applications. For more information, see
Components.

To safely organize your customizations in a class in which you can override the extension points, ensure
that:

The class is a child of the PegaAccel-Management-Refactor-Instances-Merge class.

You update the pySetCustomMergeExperience activity to conditionally set the class of the primary
page by using the page-set-class method.
If multiple merge wizard implementations are required, include this logic in the highest ruleset version
available.

For more training materials, see the Merging a development branch in 8.5 challenge on Pega Academy.

For an example of the enhancements that you can make in the branch merge process by customizing this
process, see Modifying postprocessing behavior in the branch merge process.

Modifying postprocessing behavior in the branch merge process

Enhance the branch merge process by customizing the postprocessing behavior in the Merge
Branches wizard. For example, you can configure the wizard to send an email notification with the
status of the merge process, to keep stakeholders in the case automatically informed about the merge
status.

Branches and branch rulesets

Merging branches into target rulesets

Modifying postprocessing behavior in the branch merge

process
Enhance the branch merge process by customizing the postprocessing behavior in the Merge Branches
wizard. For example, you can configure the wizard to send an email notification with the status of the
merge process, to keep stakeholders in the case automatically informed about the merge status.

Before you begin:

 1. Create a correspondence rule named MergeRuleSetsStatus. For more information, see Creating a rule
and the Rule creation module on Pega Academy.
2. Save a copy of the standard pyPostMergeInstances subprocess. For more information, see the
"Creating a class to organize your customizations" section in Branch merge process customization.

In the following example, you want the system to send the project lead an email notification about the
status of the merge process, so you use a Utility shape and the CorrNew activity.

Note: For information about other ways to send correspondence and notifications from this process, see
Engaging and notifying stakeholders and Flow shapes.

1. In Dev Studio, in the rule form of the saved copy of the pyPostMergeInstances subprocess, check out
the rule.
2. In the process diagram of the pyPostMergeInstances subprocess, add the Utility shape:
a. On the Diagram tab, click Flow Shapes, and then select the Utility shape.
b. Drag the Utility shape to the flow diagram, and place the shape based on the order of events in
the process.
c. Connect the Utility shape to the process by dragging a connector from a shape that precedes the
utility activity in the process to the Utility shape, and then dragging the end point of the
connector from the Utility shape to the connection point of the shape that follows the utility
activity on the canvas.
3. In the properties pane of the Utility shape, give a name to the shape, for example Send email to Project Lead ,
and then, in the Rule field, select the CorrNew activity.
4. In the Parameters section, in the CorrName field, select the MergeRuleSetsStatus correspondence
rule.
5. In the PartyRole field, enter Project Lead.
6. In the EmailSubject field, enter the following email subject: Status of Merge Branches operation .
7. Submit the updated utility properties, and then save the process.
8. Create a work parties rule in the PegaAccel-Management-Refactor-Instances-Merge apply to class, to
define the parties that you want to receive the email. Specify the same Project Lead role that is in the
Utility shape properties. For more information, see Defining case participants.

Result: When the merge process completes, the system performs the postprocessing step and sends an
email to the project lead by using the work parties rule.

Branch merge process customization

Merging branches into target rulesets

Creating a toggle
To enable or disable functionality that is under development, or to control access to a feature, create a
toggle. When you create a toggle, a when rule for the toggle instance is created by default.

You can also associate a toggle instance with an external project management application, so that you can
identify and remove toggles after development is complete.

1. In the header of Dev Studio, click Configure System Release Toggles .

2. Click Create new toggle.
3. Complete the following fields to configure the toggle for your application.
Application context – Select the application for which you want to create a toggle. By default,
the toggle is associated with the rulesets in this application.
Toggle identifier – Enter a unique identifier for the toggle. This identifier cannot contain spaces
or special characters.
Optional: Description – Enter a description for the toggle.
External ID – Enter the epic ID that is associated with this toggle. This field is required if you
have the Project Management Framework (PMF) enabled for the Pega Platform. If you are not
using PMF or another project management application, or if you are using a third-party project
management application, this field is optional.
4. Select the users to whom the toggle applies. Although you can select more than one option, the option
that is more inclusive supersedes the other options.
Enable toggle for all – Select this option to apply the toggle to all users of the application.
Only my access group – Select this option to apply the toggle to all users in your access group.
Only myself – Select this option to apply the toggle to the logged-in operator.
5. Select the development branch and application ruleset to which the when rule for the toggle applies.
These options are available when the Toggle will be referenced by rules check box is selected.
 This check box is selected by default. You can use the when rule to enable or disable functionality
while it is being developed and tested.
If you clear the Toggle will be referenced by rules check box, a when rule is not created for the
toggle. Instead, you can manage the toggle by using the toggle data instance in the rules of your
application.
6. Click Submit.

Reviewing and editing toggles

To keep the list of available toggles accurate, review, edit, and potentially delete the toggles in your
applications. For example, at the end of a release you can review and delete the toggles that you want
to retire.

Reviewing and editing toggles

To keep the list of available toggles accurate, review, edit, and potentially delete the toggles in your
applications. For example, at the end of a release you can review and delete the toggles that you want to
retire.

1. Click Configure System Release Toggles .

2. On the Toggle Management landing page, filter or sort the list of toggles to find the toggle that you
want to manage.
Click the Filter icon in a column heading to search for toggles with that attribute. You can select
one or more attributes from the list, or you can search for a specific attribute by entering text in
the Search Text field.
Click the arrow next to the column heading to sort the list alphabetically.
3. Click the Edit icon for the toggle that you want to update, or click the Delete icon to retire a toggle.
4. Click Submit to save your changes.

Optimizing application load time

Improve the performance of your application by reducing content that is difficult to render. By running
preflight optimization, you eliminate unnecessary static content and improve load times, which creates a
better user experience.

Before you begin: Review your compliance score, and take corrective action to reduce static content in
your application. For more information, see Improving your compliance score. The preflight optimization
tool uses MD5 to generate a unique hash for the content of the optimized files. The tool uses the MD5 hash
only to track changes in content to determine if new files need to be generated during optimization.
Because the MD5 hash is not used for security, it does not represent a system vulnerability.

1. In the header of Dev Studio, click Configure User Interface Application readiness Preflight
optimization .
2. On the Preflight Optimization screen, click Add optimization.
3. In the Add optimization configuration dialog box, complete the following steps:
a. On the Basic tab, in the Access group list, select the access group that you want to optimize.
The associated portal name is displayed on the right.
b. Under Optimize, specify whether you want to optimize JavaScript files, Cascading Style Sheet
(CSS) files, or both
c. Optional: To reduce the size of your JavaScript files by removing comments and other
unnecessary elements, select the Use JS Compacting check box.
d. On the Advanced tab, select individual rules for the analysis of the application's design-time
model.
The Skip option determines if the rule is excluded from the analysis.
e. Click Submit to save the optimization's configuration and start the analysis.

If you run the access group's preflight optimization for the first time, or if you select the Use
JS Compacting check box, the process might take a few minutes.

4. Optional: To return the application to its previous JavaScript and CSS usage temporarily, clear the
Enable check box on the Preflight Optimization screen.

You might complete this step if you encounter problems in the application and want to isolate them for
testing and correction before you repeat the optimization process.
Result: After optimization, the application uses the optimized files by default.What to do next:

View the report to see optimization details such as the difference between the original size and the
optimized size of the static content.

If you change the portal, the application, or the application’s skin, repeat the preflight optimization process
to remove any unnecessary static content introduced by your changes.

Rerunning a preflight optimization

If you change the access group's portal, the application, or the application’s skin after running the
preflight optimization process, repeat the preflight optimization to remove any unnecessary static
content or add necessary static content introduced by your changes.

Checking results and JavaScript file dependencies

View the preflight optimization report to see a list of components by category and to compare the
static content’s original size to its optimized size.

Improve application loading time with preflight optimization

Most of the static content for an application—the JavaScript files and Cascading Style Sheet (CSS) files
—loads when the user starts the application. By using preflight optimization to reduce unnecessary
static content, you can speed up your application’s initial display time, which can be especially
important for applications that users access occasionally or just once.

Rerunning a preflight optimization

If you change the access group's portal, the application, or the application’s skin after running the preflight
optimization process, repeat the preflight optimization to remove any unnecessary static content or add
necessary static content introduced by your changes.

When you move your application between different versions of Pega Platform, to optimize your content and
improve application load time, rerun the optimization on the new version of the application, even if the new
version does not include any changes. Since the underlying files that the system optimizes may change
across versions of Pega Platform, rerunning the optimization is required to ensure that the latest version of
your application has the correct content to render and the application load time meets your requirements.

The Preflight Optimization screen lists any existing optimizations, by access group, along with the optimized
portal, compact JavaScript and Cascading Style Sheet (CSS) files, and the date of the most recent update.
You can use the Enable check box to turn an existing optimization off during application testing or to turn
optimization back on after disabling it.

1. In the header of Dev Studio, click Configure User Interface Application readiness Preflight
optimization .
2. On the Preflight Optimization screen, click the Gear icon for the optimized portal.
3. In the Optimization configuration dialog box, click Submit to repeat the optimization process.

Improve application loading time with preflight optimization

Optimizing application load time
Checking results and JavaScript file dependencies

Checking results and JavaScript file dependencies

View the preflight optimization report to see a list of components by category and to compare the static
content’s original size to its optimized size.

Before you begin: Run a preflight optimization on a portal. On the report screen, you can analyze any
rule that has the Open icon displayed next to it.

1. On the Preflight Optimization screen, click the View report link for the optimized portal with static
content data that you want to review.
The Usage tab of the report screen lists the components—rules, layouts, controls, actions, and
processes—that are used in the application and their corresponding usage counts.
2. On the Usage tab, expand any component to see the rules that use that component.
 Green check marks – A component with a green check mark is used in the application. (A
component without a green check mark is not used.)

Asterisks – A component without an asterisk has a UI component definition. Click the Open icon
to display the UIComponent Definition screen, which lists the files on which the component
depends as well as any associated actions. For each file you can see the application name, file
extension, file name, and, where appropriate, the corresponding feature. A component with an
asterisk does not have a UI component definition.

3. Optional: To see all components that are available in the system, select the Show all components
check box.
4. On the Rules tab, expand folders in the hierarchical table of rules to drill down and click the Open
icon to open the rules or to see the UI component definitions.
5. On the CSS Formats tab, analyze the total number of CSS formats used by the access group (portal),
the original size of the Cascading Style Sheet files, and the optimized size, both as the actual file size
and as a percentage of the original file size.
The optimization process skips any skin elements that are not used by the application. Specifically, the
optimization skips the generation of CSS:
For all skin elements that are not in the model.
For any unused formats of skin elements that are in the model.

The optimization process also removes unnecessary CSS files, such as files that are only needed for
specific skin elements, for specific controls, for specific formats of specific controls, and so on.

6. Optional: Drill down to see detail for the CSS formats.

To see the CSS formats that used by a UI component, expand the folder that represents that
component.
To see the specific rules that use a CSS format, expand the folder that represents that format.
To open a specific rule, click the Open icon for that rule.
7. On the JS Dependencies tab, review the total number of JavaScript files optimized, the original size,
and the optimized size (and percentage saved), and explore dependencies to determine which files
you can remove without affecting your application’s functionality.
Components – Select this option to see the JavaScript files on which various components
depend. When you click the Open icon for a component, the UIComponent Definition screen is
displayed and you can view the JavaScript files on which the component is dependent.

File dependencies – Select this option to drill down from a calling component to find the
JavaScript files on which it is dependent. Click the Open icon to see the contents of the JavaScript
file.

For example, you can drill down on the pega_ui_property JavaScript file all the way to the
pzpega_ui_environment JavaScript file. You can then click the Open icon to view the contents of
the pzpega_ui_environment file on the Text File rules screen so that you can further explore its
dependencies, check JavaScript syntax, and so on.

File dependency parents – Select this option to reverse the view from the preceding option
and trace dependencies from a JavaScript file up to its calling component.

For example, to continue from the preceding example, you could instead start from the
pzpega_ui_environment JavaScript file and drill to find its calling component, the pega_ui_property
JavaScript file, to determine why the file is needed.

8. On the JS Stack tab, review the total number of JavaScript files that were optimized, listed in
dependency order; the original size; and the optimized size (and percentage of original size). Expand
sections to see where JavaScript files are included:
Included at top – This section lists all JavaScript files that are included in the JavaScript bundle,
in the head tag.
Included with Client Template – This section lists all JavaScript files that are needed for
templates. These files are bundled and included before template JSON code.
Included at bottom – This section lists the remaining JavaScript files, which are bundled and
included in the body tag near the bottom of the document.
Click the Open icon to display the contents of the JavaScript file on the Text File rules screen so that
you can check the file's syntax.

Improve application loading time with preflight optimization

Optimizing application load time
 Rerunning a preflight optimization

Improve application loading time with preflight optimization

Most of the static content for an application—the JavaScript files and Cascading Style Sheet (CSS) files—
loads when the user starts the application. By using preflight optimization to reduce unnecessary static
content, you can speed up your application’s initial display time, which can be especially important for
applications that users access occasionally or just once.

Application load time improvements are most noticeable for mobile applications that are running in areas of
reduced network speed but also apply for desktop applications.

Only necessary files are optimized

Preflight optimization analyzes an application's rule model and creates optimized JavaScript and CSS files
that are purpose-specific for the UI components that are actually used by the application.

General process
You run optimizations by access group and portal before you release your application.

After you run the process, review the optimization report to identify the UI components, rules, and CSS
formats that were included in the optimization process.

To further reduce your application's static content, you can remove more files and repeat the preflight
optimization process. Use the report to identify which files are needed for a component to work and which
files you can remove without affecting the application.

JSP <static> tags with "moveToEnd" attributes

If your application uses JavaServer Pages (JSP) <static> tags and you include a <static> tag with the
attribute "moveToEnd,"the code is not included in the optimization process.

For example, you might have the following in your application if you were to copy existing Pega code:

<pega:static type="script" app="webwb" moveToEnd="true">

<pega:bundle name=”databundle”/>

</pega:static>

With optimization turned off, this bundle of JavaScript files is included at the bottom of the HTML document.
With optimization turned on, this bundle is not included at all.

Rerunning the optimization process

When you change the portal, the application's content, or the application’s skin, repeat the preflight
optimization to remove any unnecessary static content that was introduced by your changes.

Optimizing application load time

Rerunning a preflight optimization
Checking results and JavaScript file dependencies

Improving your compliance score

Follow development best practices to improve your compliance score. By eliminating risks, such as custom
code or degraded performance, you can improve quality and resolve issues before your application goes
into production.

To maintain your application quality, try to achieve a compliance score of 90 or greater. If your application's
score becomes less than 80, take immediate action to address the issues.

1. Analyzing a compliance score

 Analyze your compliance data to find the root cause of a low compliance score. By taking action when
your application's score is less than 80, you can improve application quality more quickly.

2. Resolving an application warning

Resolve warnings to improve application quality and ensure that you follow development best
practices.

3. Justifying an application warning

Justify a warning to explain why your application is exempt from a best practice, or guardrail. By
documenting which warnings are intentionally unresolved, you can improve your compliance score.

4. Reviewing user interface components

Find out which UI elements in your application are high-maintenance. By analyzing the reports on the
UI issues landing page, you can learn how to more efficiently render process-heavy components, and
save development time during future updates.

5. Sharing your compliance score with stakeholders

Share your compliance score with stakeholders to quantify the improvements that your team makes to
application quality, performance, and maintenance.

Compliance score logic

Monitoring project compliance
Viewing application quality metrics

Analyzing a compliance score

Analyze your compliance data to find the root cause of a low compliance score. By taking action when your
application's score is less than 80, you can improve application quality more quickly.

Before you begin: Encourage your team to check in their work so that you have complete data.

1. Find your compliance score.

a. In the header of Dev Studio, click Configure Application Quality Guardrails Compliance
Score .
b. In the Compliance score section, review your weighted score.
2. Optional: To broaden the scope of your compliance data, include built-on applications.
a. Click application, and then select one or more built-on applications.
b. Click Apply.
3. Identify the highest priority issues that affect your score.
a. Click the Compliance Details tab.
b. In the Warning impact section, click the values in the Resolve now column.
c. Review the list of rules with severe warnings.
d. In the Application risk introduced by operator section, take note of the user with the highest
risk percentage.
e. Click the percentage, and then review the list of rules with warnings that the user added to your
application.
4. Identify the types of rules with the most warnings.
a. Click the Warning Summary tab.
b. In the # Rules with warnings column, review the distribution of warnings across the different
types of rules.
c. Expand the row for the rule type with the highest number of warnings.
d. Optional: For more information about a specific rule, click a rule name in the Rule column.
5. Review how your compliance score has changed over time.
a. Click the Compliance Score tab.
b. In the Rules modified on or after field, enter a date, and then click Apply date filter.

What to do next: Use the findings from your analysis to focus your improvements on specific rules and
warnings, and coach individuals on development best practices.

Monitoring project compliance

Sharing your compliance score with stakeholders
Compliance score logic
Resolving an application warning
Resolve warnings to improve application quality and ensure that you follow development best practices.

1. In the header of Dev Studio, click Configure Application Quality Guardrails Compliance Score .
2. In the Compliance score section, click the number in the Rules with unjustified warnings field.
3. In the Rule name column, click a rule to open it.
4. In the header of the rule form, click Review/Edit.
5. Review the warning message to understand which best practice your application does not follow, how
it affects your compliance score, and what to do next.
6. Click OK.
7. Update the rule by following the guidance from the warning message.
8. Click Save.

Justifying an application warning

Justify a warning to explain why your application is exempt from a best practice, or guardrail. By
documenting which warnings are intentionally unresolved, you can improve your compliance score.

Before you begin:

Ensure that your access role is associated with the pxAllWarningJustification privilege.

1. In the header of Dev Studio, click Configure Application Quality Guardrails Compliance Score .
2. In the Compliance score section, click the number in the Rules with unjustified warnings field.
3. In the Rule name column, click a rule to open it.
4. In the header of the rule form, click Review/Edit, and then review the warning to confirm that your
application can tolerate the associated risk.
5. Click Add Justification.
Note: You cannot justify some warnings, because the risk that they introduce is too severe. For these
cases, consider resolving the warning instead.
6. In the field that is displayed, enter text that explains why your development team chooses to leave
this warning unresolved.
7. Click OK.
8. Click Save.

What to do next: Periodically review the list of rules with unjustified warnings in your application because
imported rules can display new warnings when your development team resaves them.

Resolving an application warning

Reviewing user interface components

Find out which UI elements in your application are high-maintenance. By analyzing the reports on the UI
issues landing page, you can learn how to more efficiently render process-heavy components, and save
development time during future updates.

1. In the header of Dev Studio, click Configure Application Quality App Studio Compliance User
Interface .
2. In the Built on applications section, select one or more applications whose UI components you want
to review.
3. Click Apply.
4. Review the report and follow the suggestions for updating UI components.
5. Optional: To open a section that contains UI issues in a new tab, expand the relevant report header,
and then click the section name. For example: Your application contains sections that do not use a
design template. To address this issue, expand the No design template node, click the name of the
section that you want to fix, and apply a design template to that section in the section editor.

Improving your compliance score

Sharing your compliance score with stakeholders

Share your compliance score with stakeholders to quantify the improvements that your team makes to
application quality, performance, and maintenance.

You can use the following techniques to share your compliance score:

Exporting compliance data

Export compliance data to create reports that you can download and distribute later. By manually
collecting data, you can control which metrics to share with stakeholders.

Scheduling a compliance report

Schedule a compliance report to automatically inform stakeholders about changes to your

application's compliance score over time.

Exporting compliance data

Export compliance data to create reports that you can download and distribute later. By manually collecting
data, you can control which metrics to share with stakeholders.

1. In the header of Dev Studio, click Configure Application Quality Guardrails .

2. To export your compliance score:
a. Click the Compliance Score tab.
b. Optional: To capture data from a specific point in time, select a date from the Rules modified
on or after field, and then click Apply date filter.
c. Click Export to PDF.
3. To export the distribution of warnings by type, age, and owner:
a. Click the Compliance Details tab.
b. Optional: To capture data from a specific point in time, select a date from the Rules modified
on or after field, and then click Apply date filter.
c. Click Export to PDF.
4. To export a list of rules with warnings:
a. Click the Warning Details tab.
b. Optional: To capture rules from a specific class, click classes, enter a class name in the field
that is displayed, and then click Apply.
c. Click Export to Excel.

What to do next: Open and review each file that you export, because the filters that you set on the
Application Guardrails landing page are not persistent.

Scheduling a compliance report

Schedule a compliance report to automatically inform stakeholders about changes to your application's
compliance score over time.

Before you begin: Ensure that the DefaultNotify email account is configured. For more information, see
Viewing email accounts.

1. In the header of Dev Studio, click Configure Application Quality Guardrails .

2. Based on the type of data that you want to include in your report, click one of the following tabs:

Compliance Score
Summarizes the factors that contribute to your compliance score
Compliance Details
Categorizes the warnings in your application by type, age, and owner
Warning Summary
Depicts the distribution of warnings in your application by severity and rule type
Warning Details
Lists more information about the rules that introduced the warnings

3. Click Schedule report.

4. In the Email Scheduling dialog box, select the Enable email notifications check box.
5. In the Send the report list, select the frequency at which your application sends the report data in an
email.
6. Click the Add icon.
7. In the field that is displayed, press the Down Arrow key, and then select the name of a stakeholder.
 If the stakeholder is not in the list, enter an email address in the field instead.

8. Click Submit.

Exporting compliance data

Monitoring project compliance

Monitor the collective compliance score for your application and built-on applications to determine how well
your project follows development best practices.

1. In the header of Dev Studio, click Configure Application Quality Dashboard .

2. On the Compliance Score tab, click Enable historical compliance score.
3. Periodically review the graph that is displayed, to monitor how your score changes from week to week.

What to do next: If your compliance score is not displayed, review the log files for relevant error
messages.

Log files tool

Compliance score logic

A standard formula determines your compliance score. By understanding the logic and variables in this
formula, you can focus on the development changes that improve application quality the most.

The following figure presents the logic that assigns weights to the warnings in your application.

Variable definitions:

Sev1u
Severe, unjustified warnings
Sev2u
Moderate, unjustified warnings
Sev1j
Severe, justified warnings
Sev2j
Moderate, justified warnings

The sum of the variables is divided by the number of rules with informational warnings or no warnings. The
result is a positive, integer percentage.

Compliance scores apply only to the rules in your application and imported rules that you resave. Property
rules and all rules in Pega* rulesets do not affect your compliance score.

Analyzing a compliance score

Improving your compliance score

Unit testing individual rules

An incorrect rule configuration in an application can cause delays in case processing. To avoid configuration
errors such as incorrectly routed assignments, unit test individual rules as you develop them. To expedite
future rules testing, you can create reusable test cases from the unit test.

You can test a rule with test data that you provide by clicking Actions > Run on the rule form toolbar. For
some rule types, such as binary file rules, Pega does not provide an option for unit testing. If the rule
cannot be unit tested, the Run option is not available.

The appearance of the Run Rule window varies across rule types, so how you run a rule varies by its type.
In general, however, the rules run by using data from a test page that you define for the test.

Tasks involved in defining the test page include the following.

 1. Selecting a method for creating the test page – You can copy values from a thread of an existing
clipboard page to the test page, create a new test page, or reset the values of an existing test page.
For more information about clipboard pages, see Clipboard tool.
2. Applying data transforms – For a reusable and expedited method of making decisions and calculating
values, you can apply data transforms to set values for the test page. For example, to unit test a
decision table, you can create a data transform to provide values for the properties evaluated by the
table, rather than manually entering values when you run the rule. For more information about data
transforms, see Data transforms.
3. Manually entering test data – In some cases, you can manually enter values to use. If you enter values
for a test, the values that you enter override values on the test page.
4. Specifying how service rules run – For services, you also specify whether the service rule is to run in
your session or is to run as a newly created service requestor. If the service is configured to run as an
authenticated user, you are prompted for a user name and password.

Note: To test a circumstance rule, ensure that the circumstances are correct for the rule. Otherwise, the
system tests the base rule.

When you run the rule, the system uses rule resolution. If you unit test a rule, and there is a higher version
of the rule, the system runs the higher version.

After you run the test, you can also convert the test to a reusable test case that you can run at any time.
For more information about using unit test cases, see Understanding unit test cases.

Unit testing UI rules

Unit test UI rules, such as harnesses and sections.

Unit testing data model rules

Unit test data model rules, such as data pages and data transforms.

Unit testing decision rules

Unit test decision rules, such as tables, decision trees, when rules, map values, collections, and
declare expressions.

Unit testing process rules

Unit test process rules, such as flows and case types.

Unit testing report rules

Unit test report rules, such as report definitions.

Unit testing technical rules

Unit test technical rules, such as activities.

Unit testing parse rules

Types of parse rules include parse delimited rule, parse XML rule, parse structured rules.

Unit testing service rules

Unit test service rules such as, email, Java, MQ, SAP, and SOAP rules.

Viewing clipboard pages created by unit testing a rule

After running a rule, you can open the Clipboard tool and examine the output as it appears on the
resulting clipboard pages.

Unit testing UI rules

Unit test UI rules, such as harnesses and sections.

Unit testing a harness

 After you create a harness rule, you can run the rule to test it in the context of the application you are
developing. Specify a test page for the rule to use, provide sample data as the input, run the rule, and
examine the results.

Unit testing a section

After you create a section rule, you can run the rule to test it in the context of the application you are
developing. Specify a test page for the rule to use, provide sample data as the input, run the rule, and
examine the results.

Unit testing a harness

After you create a harness rule, you can run the rule to test it in the context of the application you are
developing. Specify a test page for the rule to use, provide sample data as the input, run the rule, and
examine the results.

Before you begin: Create and open the harness rule that you want to test. For more information, see
Creating harnesses. Determine how you will provide the sample data to use when testing the rule. If
possible, open a work item of the appropriate class.

1. In the navigation pane of Dev Studio, click Records User interface Harness , and then select the
harness you want to test.
2. Click Actions Run . The Run Rule window opens.
3. In the Test Page pane, select the context and test page to use for the test.
a. In the Data Context list, select the thread in which you want to run the rule. If a test page exists
for the thread, then it is listed and can be used for creating the test page.
b. Select the test page to use for the test:
Select Empty test page to start from a page containing no parameter values.
If a clipboard page exists, then you can select Copy existing page to copy values from a
thread of an existing clipboard page to the main test page.
Select Create or reset test page to create a new test page or reset the values of an
existing test page.
4. To apply a data transform to values on the test page, click the link in the Apply field, and then select
a data transform.
5. In the lower section of the Run Rule window, enter the test data and click Execute.
The system runs the harness and displays the results.
6. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.

Harnesses

Unit testing a section

After you create a section rule, you can run the rule to test it in the context of the application you are
developing. Specify a test page for the rule to use, provide sample data as the input, run the rule, and
examine the results.

Before you begin: Create and open the section rule that you want to test. Determine how you will provide
the sample data to use when testing the rule. If possible, open a work item of the appropriate class.

1. In the navigation pane of Dev Studio, click Records Decision User interface , and then select the
harness you want to test.
2. Click Actions > Run. The Run Rule window opens.
3. In the Test Page pane, select the context and test page to use for the test.
a. In the Data Context list, select the thread in which you want to run the rule. If a test page exists
for the thread, then it is listed and can be used for creating the test page.
b. Select the test page to use for the test:
Select Empty test page to start from a page containing no parameter values.
If a clipboard page exists, then you can select Copy existing page to copy values from a
thread of an existing clipboard page to the main test page.
Select Create or reset test page to create a new test page or reset the values of an
existing test page.
4. To apply a data transform to values on the test page, click the link in the Apply field, and then select
a data transform.
 5. In the lower section of the Run Rule window, enter the test data and click Execute.
The system runs the harness and displays the results.
6. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.

Sections

Unit testing data model rules

Unit test data model rules, such as data pages and data transforms.

Unit testing a data page

Test a data page to ensure that you get the expected results by using the Run Rule feature before
testing it in the context of the application that you are developing. Additionally, you can convert the
test run into a Pega unit test case for reuse.

Unit testing a data transform

You can use the Run Rule feature to test a data transform individually before testing it in the context
of the application that you are developing. Additionally, you can convert the test run into a Pega unit
test case.

Viewing test cases for a data type

You can view, run, and add test cases for a data type in the Data Designer.

Unit testing a data page

Test a data page to ensure that you get the expected results by using the Run Rule feature before testing it
in the context of the application that you are developing. Additionally, you can convert the test run into a
Pega unit test case for reuse.

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

2. Expand the Data Model category, and then click Data Page.
3. Open the data page that you want to test.
4. Click Actions Run .
5. From the Thread list in the Run context pane, select the thread in which you want to run the rule.
6. In the main test page, enter values for parameters, if any, to pass to the rule.
7. Select the Flush all instances of this data page before execution check box to delete any
existing instances of the selected data page.
8. Click Run.
9. Optional: To convert the test into a unit test case for automated testing, click Convert to Test, and
then configure the test case. For more information, see Creating unit test cases for rules.
10. Optional: Click Show Clipboard to open the Clipboard and examine the pages that are generated by
the unit test. For more information, see Clipboard pages created by the Run Rule feature.
11. Optional: If the rule has errors, click Trace to debug the rule with the Tracer tool.

Data page testing

Data page test cases are a way to validate that application data is loaded correctly. Data page test
cases compare the expected value of one or more properties with their actual values in a data page.

Data pages
Unit testing individual rules
Using the Clipboard tool
Application debugging using the Tracer tool
Creating a data page
Viewing rule history
More about data page rules

Data page testing

Data page test cases are a way to validate that application data is loaded correctly. Data page test cases
compare the expected value of one or more properties with their actual values in a data page.

Before you begin creating tests, your application must be configured for testing. See Creating a test ruleset
to store test cases.

The data page test case landing page lets you manage your data page unit tests. It lists all of the data page
tests in your application.

From the landing page you can selectively run data page test cases and view whether they have passed or
failed, see whether data pages have started experiencing changes in their run time, and create new data
page test cases. You can access tests from the Data Explorer by selecting View all test cases from the
menu at the top right of the Data Explorer.

Creating unit test cases for rules

Viewing test case results

Unit testing a data transform

You can use the Run Rule feature to test a data transform individually before testing it in the context of
the application that you are developing. Additionally, you can convert the test run into a Pega unit test
case.

1. In the navigation pane of Dev Studio, click Records Data Model Data Transform , and then select
the data transform that you want to open.
2. Click Actions Run .
3. In the Run context pane, select the thread, test page, and data transform you want to use for the
test.
a. In the Thread list, select the thread in which you want to run the rule.
b. In the Page list, select whether to copy parameter values from an existing page or to create an
empty page:

To use parameter values from an existing clipboard page in the selected thread, click Copy
existing page, and then select the page you want to copy.

To start from a page containing no parameter values, click Empty test page.

c. Optional: To apply a data transform, select the Apply data transform check box, and then
select the transform to apply.
Note: The system always runs the rule instance on the RunRecordPrimaryPage, regardless of the
page that you select from this list. If you convert this test run to a test case and the
RunRecordPrimaryPage requires initial values, then configure the clipboard so that it populates
the page with initial values. For more information, see Setting up your test environment.
4. Optional: To change the values that are passed to the rule, provide the new values on the main test
page.
5. Click Run to run the test.
6. To convert the test run into a Pega unit test case, click Convert to test, and then configure the test
case. For more information, see Creating unit test cases for rules.
7. Optional: If the rule has errors, then click Trace to debug it using the Tracer tool. For more
information, see Application debugging using the Tracer tool.
8. Click Clipboard to open the Clipboard and examine the pages that are generated by the unit test. For
more information, see Clipboard pages created by the Run Rule feature.

Data transforms
Viewing test case results
Exporting a list of test cases

Viewing test cases for a data type

You can view, run, and add test cases for a data type in the Data Designer.

1. In the navigation pane of Dev Studio, click Data types, and then select the data type for which you
want to view test cases.
2. In the Data Designer, click the Test cases tab. The test case name, data page, last run date and time,
the actual and expected run time of the data page, and the result are displayed.
3. Sort or filter the cases:
 a. To sort the cases, click the column name that you want to sort by.
b. To filter the cases, click the triangle to the right of the column name that you want to filter on.
4. Click Run selected to run the selected test.
5. Click Add new to create a new test case.

Creating a data type in Dev Studio

Running a unit test case

Unit testing decision rules

Unit test decision rules, such as tables, decision trees, when rules, map values, collections, and declare
expressions.

Unit testing a decision table

You can test a decision table individually, before testing it in the context of the application that you
are developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing a decision tree

You can use the Run Rule feature to test a decision tree individually before testing it in the context of
the application that you are developing.

Unit testing a when rule

You can test a when rule individually before testing it in the context of the application that you are
developing. Additionally, you can convert the test into a Pega unit test case to validate application
data by comparing expected property values to the actual values that are returned by the test.

Unit testing a map value

You can test a map value individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing a collection

You can test a collection individually, before testing it in the context of the application that you are
developing.

Unit testing a declare expression

You can test a declare expression individually, before testing it in the context of the application that
you are developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing event strategies

Evaluate event strategy logic by testing it against sample events. This option facilitates event strategy
design and enables troubleshooting potential issues.

Unit testing a decision table

You can test a decision table individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing a decision table involves specifying a test page for the rule to use, providing sample data as
the input, running the rule, and examining the results.

1. In the navigation pane of Dev Studio, click Records Decision Decision Table , and then select the
decision table you want to test.
2. Click Actions Run .
3. In the Data Context list, click the thread in which you want to run the rule.
4. Select a method for creating the test page.
Select Copy existing page to copy values from a thread of an existing clipboard page to the
main test page.
Select Create or reset test page to create a new test page or reset the values of an existing
test page.
 To apply a data transform to the values on the test page, click the link in the Apply field and
then select a data transform.
To clear the Result pane, click Reset Page.
To switch the current context, select a thread in the Data Context list and then click
Switch Context.
5. To display the test results, enter data in the Result panel and then click Run again. Result: The value
that you enter and the result that is returned are the values that are used for the default decision
result assertion that is generated when you convert this test to a test case.
6. Optional: To view the pages that are generated by the unit test, click Show Clipboard. For more
information, see Clipboard pages created by the Run Rule feature.
7. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
8. Optional: To view the row on the Table tab that produced the test result, click the Result Decision
Paths link. If the Evaluate All Rows option on the Results tab is selected, all the rows that are true
are highlighted.

Debugging decision tables with the Tracer

If your decision table rule does not give you the results that you expect, and you cannot determine the
problem by running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer,
you can watch each step in the evaluation of a decision table as it occurs.

Debugging decision trees with the Tracer

Unit testing individual rules
Decision tables
Running a unit test case
Viewing test case results
Exporting a list of test cases
Creating decision tables
Viewing rule history
More about Decision Tables

Debugging decision tables with the Tracer

If your decision table rule does not give you the results that you expect, and you cannot determine the
problem by running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer, you
can watch each step in the evaluation of a decision table as it occurs.

1. On the developer toolbar, click Tracer.

2. Select the ruleset that contains the rule to be traced.
a. In the Tracer window, click Settings.
b. In the Event Types to Trace section, select the Decision Table check box.
c. Select the ruleset that contains the rule to be traced.
d. Clear the other rulesets to avoid memory usage from tracing events occurring in other rulesets.
e. Click OK.
3. Return to the main portal and run the decision table.
4. Watch the Tracer output as the rule runs.

Unit testing a decision table

Unit testing a decision tree

You can use the Run Rule feature to test a decision tree individually before testing it in the context of the
application that you are developing.

You specify a test page for the rule to use, provide sample data as the input, run the rule, and examine the
results. Additionally, you can convert the test run to a Pega unit test case.

1. In the navigation pane of Dev Studio, click Records Decision Decision Tree , and then select the
decision tree you want to test.
2. Click Actions Run .
3. In the Data Context list, click the thread in which you want to run the rule.
4. Select a method for creating the test page.
Select Copy existing page to copy values from a thread of an existing clipboard page to the
 main test page.
Select Create or reset test page to create a new test page or reset the values of an existing
test page.
To apply a data transform to the values on the test page, click the link in the Apply field and
then select a data transform.
To clear the Result pane, click Reset Page.
To switch the current context, select a thread in the Data Context list and then click
Switch Context.
5. To display the test results, enter data in the Result panel and then click Run again. Result: The value
that you enter and the result that is returned are the values that are used for the default decision
result assertion that is generated when you convert this test to a test case.
6. Optional: To view the pages that are generated by the unit test, click Show Clipboard. For more
information, see Clipboard pages created by the Run Rule feature.
7. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
8. Optional: To view the row on the Decision tab that produced the test result, click the Result
Decision Paths link.

Debugging decision trees with the Tracer

If your decision tree does not give you the results you expect and you cannot determine the problem
by running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer you can
watch each step in the evaluation of a decision tree as it occurs.

Unit testing individual rules

About Decision Trees
Running a unit test case
Viewing test case results
Exporting a list of test cases
Creating decision trees
Viewing rule history
More about Decision Trees

Debugging decision trees with the Tracer

If your decision tree does not give you the results you expect and you cannot determine the problem by
running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer you can watch
each step in the evaluation of a decision tree as it occurs.

1. On the developer toolbar, click Tracer.

2. Select the ruleset that contains the rule to be traced.
a. In the Tracer window, click Settings.
b. In the Event Types to Trace section, select the Decision Tree check box.
c. Select the ruleset that contains the rule to be traced.
d. Clear the other rulesets to avoid memory usage from tracing events occurring in other rulesets.
e. Click OK.
3. Return to the main portal and run the decision tree.
4. Watch the Tracer output as the rule runs.

Unit testing a decision tree

Unit testing a when rule

You can test a when rule individually before testing it in the context of the application that you are
developing. Additionally, you can convert the test into a Pega unit test case to validate application data by
comparing expected property values to the actual values that are returned by the test.

In a continuous delivery environment, Pega unit testing provides you with feedback on the quality of your
applications, so that you can quickly identify issues and correct them.

By default, when you run the when rule, the result assertion uses the input value that you enter and the
result that is returned. The assertion is generated when you convert this test to a test case.

1. In the navigation pane of Dev Studio, click Records Decision When , and then select the when rule
 that you want to test.
2. Click Actions Run .
3. In the Run context pane, select the thread, test page, and data transform you want to use for the
test.
a. In the Thread list, select the thread in which you want to run the rule.
b. In the Page list, select whether to copy parameter values from an existing page or to create an
empty page:

To use parameter values from an existing clipboard page in the selected thread, click Copy
existing page, and then select the page you want to copy.

To start from a page containing no parameter values, click Empty test page.

c. Optional: To apply a data transform, select the Apply data transform check box, and then
select the transform to apply.
Note: The system always runs the rule instance on the RunRecordPrimaryPage, regardless of the
page that you select from this list. If you convert this test run to a test case and the
RunRecordPrimaryPage requires initial values, then configure the clipboard so that it populates
the page with initial values. For more information, see Setting up your test environment.
4. Optional: To change the values that are passed to the rule, provide the new values on the main test
page.
5. Click Run to run the test.
6. To convert the test run into a Pega unit test case, click Convert to test, and then configure the test
case. For more information, see Creating unit test cases for rules.
7. To view the pages that are generated by the unit test, click Clipboard. For more information, see
Clipboard pages created by the Run Rule feature.
8. If the rule has errors, then debug it using the Tracer tool. For more information, see Application
debugging using the Tracer tool.

Debugging when rules with the Tracer

If your when rule does not give you the results you expect and you cannot determine the problem by
running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer, you can
watch each step in the evaluation of a when rule as it occurs.

When Condition rules

Unit testing individual rules
Using the Clipboard tool
Viewing test case results
Application debugging using the Tracer tool

Debugging when rules with the Tracer

If your when rule does not give you the results you expect and you cannot determine the problem by
running the rule and examining the clipboard pages, run the Tracer tool. With the Tracer, you can watch
each step in the evaluation of a when rule as it occurs.

1. Click Tracer on the developer toolbar in Dev Studio.

2. In the Tracer window, click Settings.
3. In the Event Types to Trace section, select When rule.
4. Select the ruleset that contains the rule to be traced. Clear the other rulesets to avoid memory usage
from tracing events occurring in other rulesets.
5. Click OK.
6. Return to the main portal and run the when rule.
7. Watch the Tracer output as the rule runs.

Unit testing a when rule

Unit testing a map value

You can test a map value individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Testing a map value involves specifying a test page for the rule to use, providing sample values for
required parameters, running the rule, and then examining the test results.

1. In the navigation pane of Dev Studio, click Records Decision Map Value , and then click the map
value that you want to test.
2. Click Actions Run .
3. In the Test Page pane, select the context and test page to use for the test:
a. In the Data Context list, click the thread in which you want to run the rule. If a test page exists
for the thread, then it is listed and is used for creating the test page.
b. To discard all previous test results and start from a blank test page, click Reset Page.
c. To apply a data transform to the values on the test page, click the data transform link, and then
select the data transform you want to use.
4. Enter sample values to use for required parameters in the Results pane and then click Run Again.
Result: The value that you enter and the result that is returned are the values that are used for the
default decision result assertion that is generated when you convert this test to a test case.
5. Optional: To view the pages that are generated by the unit test, click Show Clipboard.
6. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
7. Optional: To view the row that produced the test result, click a Result Decision Paths link.

About Map Values

Unit testing individual rules
Using the Clipboard tool
Opening a unit test case
Application debugging using the Tracer tool

Unit testing a collection

You can test a collection individually, before testing it in the context of the application that you are
developing.

You specify a test page for the rule to use, provide sample data as the input, run the rule, and examine the
results. Additionally, you can convert the test run into a Pega unit test case.

1. In the navigation pane of Dev Studio, click Records Decision Collection , and then select the
collection that you want to test.
2. Click Actions Run .
3. In the Run context pane, select the thread, test page, and data transform you want to use for the
test.
a. In the Thread list, select the thread in which you want to run the rule.
b. In the Page list, select whether to copy parameter values from an existing page or to create an
empty page:

To use parameter values from an existing clipboard page in the selected thread, click Copy
existing page, and then select the page you want to copy.

To start from a page containing no parameter values, click Empty test page.

c. Optional: To apply a data transform, select the Apply data transform check box, and then
select the transform to apply.
Note: The system always runs the rule instance on the RunRecordPrimaryPage, regardless of the
page that you select from this list. If you convert this test run to a test case and the
RunRecordPrimaryPage requires initial values, then configure the clipboard so that it populates
the page with initial values. For more information, see Setting up your test environment.
4. Optional: To change the values that are passed to the rule, provide the new values on the main test
page.
5. Click Run to run the test.
6. To convert the test run into a Pega unit test case, click Convert to test, and then configure the test
case. For more information, see Creating unit test cases for rules.
7. Optional: If the rule has errors, then click Trace to debug it using the Tracer tool. For more
information, see Application debugging using the Tracer tool.
8. Click Clipboard to open the Clipboard and examine the pages that are generated by the unit test. For
more information, see Clipboard pages created by the Run Rule feature.

Unit testing individual rules

Running a unit test case
 Viewing test case results
Exporting a list of test cases

Unit testing a declare expression

You can test a declare expression individually, before testing it in the context of the application that you
are developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing a declare expression involves specifying a test page for the rule to use, providing sample data
as the input, running the rule, and examining the results.

You can unit test Declare Expression rules for which all properties referenced in the expression belong to a
single Applies To class or to one class plus superclasses of that class. For example, you cannot use this
facility to test a computation that involves both a Data-Account property and an Assign-Workbasket
property.

The following considerations apply when unit testing a declare expression:

Using data transforms – You can unit test a declare expression by using a data transform to set
property values or by manually entering values if all properties in the computation are Single Value
properties and they belong to a single Applies To class.
Testing expressions involving aggregate properties – If the expressions involve aggregate properties,
use this facility only with Page Group or Page List properties with a small number of elements.
Avoiding infinite loops – To avoid infinite loops caused by recursion, this facility uses an internal limit
of 999 computations, counting both iterations over List and Group properties and expression
evaluations. If this limit is reached during a test execution, the evaluation ends with an error message.

Testing expressions involving special properties – Your expression can involve special properties
(standard properties with names starting with px or your properties marked as special), Value List, or
Value Group properties. You cannot use manual inputs to change the value of a special property.
Instead, you can make changes to special properties by using a data transform.

1. In the navigation pane of Dev Studio, click Records Decision Declare Expression , and then select
the declare expression that you want to test.
2. Click Actions Run .
3. In the Test Page pane, select the context and test page to use for the test:
a. In the Data Context list, click the thread in which you want to run the rule. If a test page exists
for the thread, then it is listed and is used for creating the test page.
b. To discard all previous test results and start from a blank test page, click Reset Page.
c. To apply a data transform to the values on the test page, click the data transform link, and then
select the data transform you want to use.
4. In the bottom area of the window, enter values to use for the properties in the declarative network. For
each property value, click the property, enter a value for the property in the Property field, and then
click Update. Each time an input property is changed, the expression is automatically reevaluated.
5. If the unit test of the Declare Expression rule requires creating an input that is part of an embedded
Page List or Page Group property, create a new page by performing the following actions:
a. Select the Add new page check box.
b. For a Page Group, enter an identifier as a subscript value.
For a Page List, the system appends the new page after existing pages.
c. From the Class list, select the class of the page.
d. Click Update.
You can also add inputs to Value List or Value Group properties.
6. To convert the test run into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.

About Declare Expression rules

Declarative network
More about Declare Expression rules

Unit testing event strategies

Evaluate event strategy logic by testing it against sample events. This option facilitates event strategy
design and enables troubleshooting potential issues.
 1. Open the Event Strategy rule instance that you want to test by performing the following actions:
a. In Dev Studio, click Records Decision Event Strategy .
b. Click the name of an Event Strategy rule.
2. In the top-right corner of the Event Strategy rule form, click Actions Run .
3. In the Input Events field of the Run window, enter the number of events to send simultaneously.
You can send up to 100 events while the Run window is open.
4. If the event strategy is using the system time, set the Simulate system time setting.
The method for setting the event time is configured in the Real-time data component. For test
events that use system time, the value is converted to the Pega Time format (YYYYMMDD'T'HHmmss.SSS),
GMT, and stored in the pzMockedSystemTime property.
5. If the event strategy is using a custom event field to set the time, populate that field with a correctly
formatted value.
The time format for the custom event field that sets the time property is configured in the Real-time
data component.
6. If the event strategy is referencing lookup fields, simulate the corresponding values in the Lookup
section.
Note: For every lookup field that corresponds to a unique event key, only the initial lookup value is
considered. That value does not change for all subsequent events for that key.

For example, if you set the initial value of the lookup field Month to April for Customer-1234, this value
never changes for the following events, even if you simulate the next event for that customer with a
different Month value, for example, May .

7. Click Run to confirm your settings and test the strategy against sample data.
You can inspect whether the strategy produces expected results in the Sent events and Emitted
events sections. Each time you click Run, the number of available events decreases. You can reset
the number of available events by clicking Clear events.Important:

Each event that you insert for testing is validated in the same way as in a real-life event strategy run.
For example, to avoid validation errors, insert events chronologically and ensure the values must
correspond to property types, and so on.

About Event strategy rule

Creating unit test cases for rules

Unit testing process rules

Unit test process rules, such as flows and case types.

Unit testing a flow action

The Run Rule feature enables you to test a flow action individually before testing it in the context of
the application you are developing. You specify a test page for the rule to use, provide sample data as
the input, run the rule, and examine the results.

Unit testing a flow

You can test a flow individually before testing it in the context of the entire application that you are
developing.

Unit testing a flow action

The Run Rule feature enables you to test a flow action individually before testing it in the context of the
application you are developing. You specify a test page for the rule to use, provide sample data as the
input, run the rule, and examine the results.

Before you begin

Before you begin, determine how you will provide the sample data to use when testing the rule. If possible,
open a work item of the appropriate work type.

For general information about the Run Rule feature, including a list of the clipboard pages that are
generated when a rule runs, see Unit testing individual rules.

Run the rule

To run the rule, complete the following steps:

1. Save the rule.

2. Complete any preprocessing necessary to create the appropriate clipboard context and, if the rule is
circumstanced or time-qualified, to set the conditions you want to test.
3. Click the Run toolbar button. The Run Rule window appears.
4. In the Test Page section, specify which page to use as the main page. Do one of the following:
If any pages of the rule's Applies To class already exist, select one to be copied. (If this decision
tree applies to an embedded page, identify a top-level page that contains the embedded page or
pages and supply a Page Context.)
Otherwise, select Create or Reset Test page. Then, in the Apply field, select the data transform to
use for the test page.
5. If the rule being tested is circumstance-qualified, select Set circumstance properties to run exact
version of rule.
6. In the lower section of the Run Rule window, enter the test data and click Run Again. The system runs
the decision tree and displays the results.
7. Optional. Click Show Clipboard to open the Clipboard and examine the pages. Click the Hide
Clipboard button to close the tool. For information about the clipboard pages that are generated, see
Unit testing individual rules.

About Flow Actions

Text File rules - Completing the Create, Save As, or Specialization form
More about report definition rules

Unit testing a flow

You can test a flow individually before testing it in the context of the entire application that you are
developing.

You run through the flow, provide sample data as the input, and examine the behavior and results to see if
they are what you expect. When you test a flow, the system creates new test page, starts running the flow,
and creates a case.

1. In the navigation pane of Dev Studio, click Records Flow , and then select the flow.
2. Click Actions Run from the toolbar.
3. Step through each decision or assignment, providing input in each step.
4. Run through the rule as many times as necessary, testing each possible path.

Unit testing individual rules

Viewing test coverage reports

Unit testing report rules

Unit test report rules, such as report definitions.

Unit testing a report definition

You can test a report definition individually, before testing it in the context of the application that you
are developing. Additionally, you can convert the test into a Pega unit test case to validate application
data.

Unit testing a report definition

You can test a report definition individually, before testing it in the context of the application that you are
developing. Additionally, you can convert the test into a Pega unit test case to validate application data.

In a continuous delivery environment, Pega unit testing provides you with feedback on the quality of your
applications, so that you can quickly identify issues and correct them.

1. In the navigation pane of Dev Studio, click Records Reports Report Definition , and then select the
report definition that you want to test.
2. Click Actions Run .
3. To convert the report definition test run into a Pega unit test case, click Convert to test and then
configure the unit test case. For more information, see Creating unit test cases for rules.
 4. Optional: To edit the report, click Edit Report and then make the changes. For more information,
see Editing a report.
5. Optional: In the Actions list, you can also select to refresh the report, save a copy of the report,
summarize and sort the report, convert the report from a summary into a list (if applicable), and
export the report to a PDF or Excel file.

Report definitions
Unit testing individual rules
Creating unit test cases for rules

Unit testing technical rules

Unit test technical rules, such as activities.

Unit testing an activity

You can test an activity individually before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

Unit testing an activity

You can test an activity individually before testing it in the context of the application that you are
developing. Additionally, you can convert the test run to a Pega unit test case.

You can use unit test the activity if one of the following criteria is met:

The Require Authentication to run check box is selected on the Security tab of the Activity form.
Your access role allows you to update rules that have the Applies To class of this activity.

1. In the navigation pane of Dev Studio, click Records Technical Activity , and then select the activity
that you want to open.
2. Click Actions Run .
3. In the Run context pane, select the thread, test page, and data transform you want to use for the
test.
a. In the Thread list, select the thread in which you want to run the rule.
b. In the Page list, select whether to copy parameter values from an existing page or to create an
empty page:

To use parameter values from an existing clipboard page in the selected thread, click Copy
existing page, and then select the page you want to copy.

To start from a page containing no parameter values, click Empty test page.

c. Optional: To apply a data transform, select the Apply data transform check box, and then
select the transform to apply.
Note: The system always runs the rule instance on the RunRecordPrimaryPage, regardless of the
page that you select from this list. If you convert this test run to a test case and the
RunRecordPrimaryPage requires initial values, then configure the clipboard so that it populates
the page with initial values. For more information, see Setting up your test environment.
4. Optional: To change the values that are passed to the rule, provide the new values on the main test
page.
5. Click Run to run the test.
6. To convert the test run into a Pega unit test case, click Convert to test, and then configure the test
case. For more information, see Creating unit test cases for rules.
7. Optional: If the rule has errors, then click Trace to debug it using the Tracer tool. For more
information, see Application debugging using the Tracer tool.

Clipboard contents created from activity unit tests

When you test activities with the Run Rule feature, the system might create one or more clipboard
pages, including copies of the named pages that you specified in the Run dialog box. The system
retains these pages when you close the dialog box; properties on these pages remain available for you
to use when you perform subsequent testing of this or other rules with the Run Rule feature.

Testing an activity in context

 If the activity requires extensive setup and is more appropriately tested in context rather than through
unit testing, you can trigger the Tracer to start only when the activity is reached.

Viewing test coverage reports

Unit testing individual rules
Using the Clipboard tool
Opening a unit test case
Application debugging using the Tracer tool

Clipboard contents created from activity unit tests

When you test activities with the Run Rule feature, the system might create one or more clipboard pages,
including copies of the named pages that you specified in the Run dialog box. The system retains these
pages when you close the dialog box; properties on these pages remain available for you to use when you
perform subsequent testing of this or other rules with the Run Rule feature.

If the activity returns results to a parameter marked as Out on the Parameter tab of the activity, you cannot
see the results in the Clipboard. Out parameters reside on the parameter page of the activity, which you
can view only with the Tracer tool. To simplify testing, you can modify the activity temporarily to store an
Out parameter value in a property that is visible on a clipboard page. Delete the temporary step when you
finish testing.

Testing an activity in context

If the activity requires extensive setup and is more appropriately tested in context rather than through unit
testing, you can trigger the Tracer to start only when the activity is reached.

To test an activity in the context of other activities and rules that produce the needed initial conditions,
complete the following actions:

1. Open the activity.

2. Select Actions > Trace. The Tracer tool starts.
3. To avoid using more memory than needed while tracing, click Settings in the Tracer window and
ensure that only the ruleset containing the activity is selected in the Rulesets To Trace section.
4. Begin the other processing that eventually calls the activity in your own requestor session. Tracer
output begins when the activity starts.

Application debugging using the Tracer tool

Unit testing parse rules

Types of parse rules include parse delimited rule, parse XML rule, parse structured rules.

Unit testing a Parse Delimited rule

You can test a Parse Delimited rule directly, separate from the activity or other context in your
application in which it eventually operates.

Unit testing a Parse XML rule

You can test a Parse XML rule directly, separate from the activity or other context in your application
in which it will ultimately operate.

Unit testing a Parse Structured rule

You can test a Parse Structured rule directly, separate from the activity or other context in your
application in which the rule ultimately operates. By unit testing your Parse Structured rules, you avoid
configuration errors and improve application maintenance.

Unit testing a Parse Delimited rule

You can test a Parse Delimited rule directly, separate from the activity or other context in your application
in which it eventually operates.
Before you begin:

1. Create a Parse Delimited rule. For more information, see Creating a Parse Delimited rule.
2. Review the basics of unit testing. For more information, see Unit testing individual rules.

For a simple test, obtain some test data. You can type or paste the data into a form, store it in a local
Windows file, or upload it into a text file rule.

1. Save the Parse Delimited rule that you want to unit test.
2. Click Actions Run . Result: A guided test window opens.
3. Select a radio button to indicate the source of the test data.
4. If the data is to be entered directly, type or paste the data into the text area.
5. If the data is in a local file, click Choose File and navigate to the file. Then, click Open.
6. If the test data is in a text file rule, enter all three key parts of the rule that are separated by periods.
7. Click Execute to evaluate the rule. Result: An XML document is displayed in a new window, showing
properties and the corresponding parsed values. The clipboard is not altered; no properties are
updated.

Parse Delimited rules

Unit testing a Parse XML rule

You can test a Parse XML rule directly, separate from the activity or other context in your application in
which it will ultimately operate.

Preparation
For a simple test, obtain an XML document containing test data. You can choose to type or paste the data
into a form, store it in a local Windows file, or upload it into a text file rule.

Conducting the test

For basics of unit testing, see Unit testing individual rules.

1. Save the Parse XML form.

2. Click Run or the equivalent keyboard shortcut CTRL + R. A test window opens.
3. Select a radio button to indicate the source of test data.
4. If the data is to be entered directly, type or paste the data into the text area. If the data is in a local
file, click Browse and navigate to the file. Click OK. If the test data is in a text file rule, enter all three
key parts of the rule separated by periods.
5. Click Execute. A resulting XML document appears in a new window, showing properties and the
corresponding values. The clipboard is not altered.

Using the Tracer

To trace Parse XML rules:

1. Open the Tracer.

2. Click Settings to open the Tracer Settings panel.
3. Under the Rule Types to Trace section, select the Parse Rules check box.

See Configuring Tracer settings.

Viewing test coverage reports

Unit testing a Parse Structured rule

You can test a Parse Structured rule directly, separate from the activity or other context in your application
in which the rule ultimately operates. By unit testing your Parse Structured rules, you avoid configuration
errors and improve application maintenance.

Before you begin:

1. Create a Parse Structured rule. For more information, see Creating a Parse Structured rule.
 1. Create a Parse Structured rule. For more information, see Creating a Parse Structured rule.
2. Review the basics of unit testing. For more information, see Unit testing individual rules.

For a simple test, obtain an XML document that contains test data. You can choose to manually enter or
paste the document data into a form, store it in a local Windows file, or upload it into a Text File rule.

1. Save the Parse Structured form that you want to unit test.
2. Click Actions Run . Result: A guided test window opens.
3. In the Thread field, select Standard or Test to indicate the source of the test data.
4. In the Page field, select one of the following options:
Empty test page – To use a new empty page to provide input property values for the test.
Copy existing page – To use an existing page to provide input property values for the test.
5. If you select Test and Copy existing page in steps 3 and 4 respectively, in the Page to copy field,
enter the existing page that you want to copy to provide the input property values to test.
6. To set values for the test page, click Apply data transform.
Clicking this option allows for a reusable and expedited method of making decisions and calculating
values.
7. Click Run. Result: The resulting parsed XML document appears in a new window. The clipboard is
unaltered.

Parse Structured rules

Application debugging using the Tracer tool

Unit testing service rules

Unit test service rules such as, email, Java, MQ, SAP, and SOAP rules.

Providing test data when unit testing service rules

When unit testing service rules, you can provide some representative data for the service rule either
by typing or pasting in text, or by identifying an activity that will generate the test data.

Unit testing a Service EJB rule

Use the unit testing feature to verify that the operations of a Service EJB rule function correctly before
you add the external client to your testing process.

Unit testing a Service Email rule

Use the unit testing feature to verify that the operations of a Service Email rule function correctly
before you add an external component to your testing process.

Unit testing a Service File rule

Use the unit testing feature to verify that the operations of a service file rule function correctly before
you add an external component to your testing process.

Unit testing a Service HTTP rule

Use the unit testing feature to verify that the operations of a Service HTTP rule function correctly
before you add the external client to your testing process.

Unit testing a Service Java rule

Use the unit testing feature to verify that the operations of a Service Java rule function correctly before
you add the external client to your testing process.

Unit testing a Service JMS rule

Use the unit testing feature to verify that the operations of a Service JMS rule function correctly before
you add an external component to your testing process.

Unit testing a Service JSR 94 rule

Use the unit testing feature to verify that the operations of a Service JSR 94 rule function correctly
before you add the external client to your testing process.
 Unit testing a Service dotNet rule

Use the unit testing feature to verify that the operations of a Service dotNet rule function correctly
before you add the external client to your testing process.

Unit testing a Service MQ rule

Use the unit testing feature to verify that the operations of a Service MQ rule function correctly before
you add an external component to your testing process.

Unit testing a Service SAP Rule

Services start their processing in response to a request from an external application. Before you add
the external application to your testing process, use the Simulate SOAP Service Execution feature to
verify that the service processes data appropriately. When using this feature, you manually provide
some representative data to process. You specify a test page for the rule to use, provide sample data
as the input, run the rule, and examine the results to see if they are what you expect.

Unit testing a Service SAPJCo rule

Use the unit testing feature to verify that the operations of a Service SAPJCo rule function correctly
before you add the external client to your testing process.

Unit testing a Service SOAP rule

Services start their processing in response to a request from an external application. Before you add
the external application to your testing process, use the Simulate SOAP Service Execution feature to
verify that the service processes data appropriately. When using this feature, you manually provide
some representative data to process. You specify a test page for the rule to use, provide sample data
as the input, run the rule, and examine the results to see if they are what you expect.

Providing test data when unit testing service rules

When unit testing service rules, you can provide some representative data for the service rule either by
typing or pasting in text, or by identifying an activity that will generate the test data.

Determine the source of the test data

Before you begin, determine how you to provide the sample data for the rule to process. Each service rule
type has different options.

Service Type Test Data Options

Manually provide values for each parameter.

EJB, HTTP, JMS, Java, JSR
If the request data includes objects rather than scalar values, identify an
94, and MQ
activity that sets the values.

Email Manually provide values for the subject and body of the email message.

Manually provide content that is similar to file input.

File
Browse to and select a test input file for the service to process.

Additionally, if the rule has data mappings for request headers, you must
SOAP and .NET
enter values for them, too.

Create activities that set up request data

If the EJB, HTTP, JMS, Java, JSR 94, or MQ service rule that you want to test receives objects rather than
scalar values in the request, you cannot provide request values directly in the unit testing form. Instead,
create and identify an activity that sets the request values.
The Data-Admin-IS-ClientSimulation class is a helper class for the unit testing feature. A page of class Data-
Admin-IS-ClientSimulation serves as temporary storage location for the test data that the unit testing
feature uses to test a service rule. Your activity must create a page named pySimulationDataPage for the Data-
Admin-IS-ClientSimulation class and store the test request data on that page.

For the test message data, configure the activity to put the values in the Java Object List property
named pyRequestObjectValues.
If the test message is for an HTTP, JMS, or MQ service, your simulation activity must also provide any
information that is required for header fields or message properties.
Use the Value Group property named pyRequestHeaderGroup to store test data for HTTP, JMS, or MQ
header fields.
Use the Value Group property named pyRequestPropertyGroup to store test data for JMS message
properties.

For an example, locate and open one of the following standard activities:

Rule-Service-.SetRequestData
Data-Admin-IS-ClientSimulation.SetRequestData

You can use one of these activities as the template for yours: save it into the appropriate RuleSet and
specify the same Applies To class as that specified as the primary page class on the Service tab of the
service rule that you want to test.

Unit testing individual rules

Unit testing a Service EJB rule

Use the unit testing feature to verify that the operations of a Service EJB rule function correctly before you
add the external client to your testing process.

Note: Service EJB rules are no longer being actively developed, and are being considered for deprecation
in upcoming releases. Using Service EJB rules does not follow Pega development best practices. Consider
other implementation options instead.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions > Run.
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard)
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:
 Specify individual request values — This option appears only if the EJB method
Field Description
parameters are scalar values, such as strings, numbers, or booleans.
Enter Request
Data Invoke Initialization activity — A test activity creates values for the EJB method
values.

Method If you selected Specify individual request values for the previous field, enter in the
Parameter Value field a literal constant value for each EJB method parameter declared on the
Values Parameters tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity , enter here the Activity Name key part of
an activity that creates EJB method parameters. The system assumes the Applies To
Activity class of the activity matches the Primary Page Class value on the Service tab. If the
activity applies to a different class, enter the class name, a period, and the activity
name.

Viewing test coverage reports

Unit testing a Service Email rule

Use the unit testing feature to verify that the operations of a Service Email rule function correctly before
you add an external component to your testing process.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see Testing Services and Connectors, a document in the Integration area of
the Pega Community.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described below, and then click Execute.

Requestor context - Select a context to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including your RuleSet list,
privileges, and current clipboard).

Initialize service requestor context — Create a new requestor session based on the APP requestor type
and, if the service package requires authentication, another Operator ID instance.

Authentication user ID - If you selected Initialize service requestor context, and the service package
instance for the service requires authentication, enter the Operator ID to be used to test the service.

Authentication password - If you selected Initialize service requestor context, and the service package
instance for the service requires authentication, enter a password for the Operator ID.

Enter request data

Message header values - Enter one value for each message header declared on the Request tab.

Message content - Type or paste in the text that forms the content of the arriving email message.

Activity for adding attachments - If the arriving test message is to include email attachments, identify here
the Activity Name key part of the test activity described above.

Viewing test coverage reports

Tracing services

Unit testing a Service File rule

Use the unit testing feature to verify that the operations of a service file rule function correctly before you
add an external component to your testing process.

Before you begin, see How to provide test data when testing service rules.

Note: Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see Testing Services and Connectors, a document available from the
Integration pages of the Pega Community.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard).
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select:

Supply File Content if you will type in or paste in the text of a test file. This option
Enter Request
is not available if non-text input is expected — that is, if the Data Mode field on
Data
the Method tab is set to a value other than text only .
Upload a local file if the test file is on your workstation or network.

Enter the contents of a test file, including delimiters. This text area appears when you
File Content
choose Supply File Content for the previous field.

Click Browse to upload a test file. This field appears when you choose Upload a local
File Location
file for the previous field.

Service File rules

Unit testing a Service HTTP rule

Use the unit testing feature to verify that the operations of a Service HTTP rule function correctly before
you add the external client to your testing process.

Important: Service HTTP rules are no longer being actively developed. To avoid upgrade issues when
these rules are deprecated, use Service REST rules instead. For more information about Service REST rules,
see Service REST rules.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

 1. Save the rule form.
2. Start the Tracer by clicking Actions > Trace. For more information, see Tracing services.
3. Click Actions > Run.
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard)
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — Select if you want to manually enter the
Enter Request values for the message data in the Message Buffer text box.
Data
Invoke Initialization activity — Select if you want to run an activity that creates
the string for the message data.

HTTP Header If you selected Specify individual request values for the previous field, enter in the
Values Value field a literal constant value for each Header Field row on the Request tab.

Message If you selected Specify individual request values , enter or paste the test message data
Buffer in this text box.

If you selected Invoke Initialization activity, specify the Activity Name key part of an
activity that creates the message. The system assumes the Applies To class of the
Activity
activity matches the Primary Page Class value on the Service tab. If the activity applies
to a different class, enter the class name, a period, and the activity name.

Viewing test coverage reports

Unit testing service rules

Unit testing a Service Java rule

Use the unit testing feature to verify that the operations of a Service Java rule function correctly before you
add the external client to your testing process.

Note: Service Java rules are no longer being actively developed, and are being considered for deprecation
in upcoming releases. Using Service Java rules does not follow Pega development best practices. Consider
other implementation options instead.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
 4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
your RuleSet list, privileges, and current clipboard).
Requestor
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only if the Java method
Enter Request parameters are scalar values, such as strings, numbers, or booleans.
Data
Invoke Initialization activity — A test activity creates values for the Java method
values.

Method If you selected Specify individual request values for the previous field, enter in the
Parameter Value field a literal constant value for each Java method parameter declared on the
Values Parameters tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity, enter here the Activity Name key part of an
activity that creates Java method parameters. The system assumes the Applies To
Activity class of the activity matches the Primary Page Class value on the Service tab. If the
activity applies to a different class, enter the class name, a period, and the activity
name.

Viewing test coverage reports

Unit testing a Service JMS rule

Use the unit testing feature to verify that the operations of a Service JMS rule function correctly before you
add an external component to your testing process.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard).
Context Initialize service requestor context — Create a new requestor session based on
 Initialize service requestor context — Create a new requestor session based on
Field the APP requestor type and, ifDescription
the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only if all the JMS buffer
Enter Request fields are scalar values, such as strings, numbers, or Booleans.
Data
Invoke Initialization activity — A test activity creates values for the JMS request
message and for any headers or JMS properties.

If you selected Specify individual request values for the previous field, enter in the
Message
Value field a literal constant value for each header field declared on the Request tab.
Header Values
Enter a value that corresponds to the Java data type listed.

Message If you selected Specify individual request values for the previous field, enter in the
Property Value field a literal constant value for each message field declared on the Request tab.
Values Enter a value that corresponds to the Java data type listed.

If you selected Specify individual request values for the previous field, enter in the
Message
Value field a literal constant value for each message buffer field declared on the
Buffer Values
Request tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity , enter here the Activity Name key part of
Activity for an activity that creates JMS message elements. The system assumes the Applies To
Initializing class of the activity matches the Primary Page Class value on the Service tab. If the
Message Data activity applies to a different class, enter the class name, a period, and the activity
name.

Unit testing a Service JSR 94 rule

Use the unit testing feature to verify that the operations of a Service JSR 94 rule function correctly before
you add the external client to your testing process.

Note: Service JSR94 rules are no longer being actively developed, and are being considered for
deprecation in upcoming releases. Using Service JSR94 rules does not follow Pega development best
practices. Consider other implementation options instead.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
your RuleSet list, privileges, and current clipboard).
Requestor
 Context
Field Initialize service requestor context — Create a new requestor session based on
Description
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context, and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context, and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only if the JSR94 input
Enter Request parameters are scalar values, such as strings, numbers, or booleans.
Data
Invoke Initialization activity — A test activity creates values for the JSR94 input
parameter values.

Input If you selected Specify individual request values for the previous field, enter in the
Parameter Value field a literal constant value for each input method parameter declared on the
Values Request tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity, enter here the Activity Name key part of an
activity that creates JSR94 input parameters. The system assumes the Applies To class
Activity
of the activity matches the Primary Page Class value on the Service tab. If the activity
applies to a different class, enter the class name, a period, and the activity name.

Viewing test coverage reports

Unit testing a Service dotNet rule

Use the unit testing feature to verify that the operations of a Service dotNet rule function correctly before
you add the external client to your testing process.

Important: Service dotNet rules are no longer being actively developed, and are being considered for
deprecation in upcoming releases. Using Service dotNet rules does not follow Pega development best
practices. Use Service SOAP rules instead. For more information, see Service SOAP rules.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see Testing Services and Connectors, a document on the Integration pages
of the Pega Community.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions > Trace. For more information, see Tracing services.
3. Click Actions > Run.
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your requestor session (including your
Requestor RuleSet list, privileges, and current clipboard)
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

Authentication If you selected Initialize service requestor context , and the service package instance
 User
FieldID for the service requires authentication, enter the Operator ID to be used to test the
Description
service

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only when all elements of
Enter Request the message are simple text values not objects or complex values of type XML Page.
Data
Supply SOAP Envelope — You provide the entire SOAP message including the
header.

If you selected Specify individual request values for the previous field, enter in the
SOAP Header
Value field a literal constant value for each Header Field row on the Request tab. Enter
Values
a value that matches the XSD type shown.

SOAP If you selected Specify individual request values for the previous field, enter in the
Parameter Value field a literal constant value for each Request Parameters row listed on the
Values Request tab. Enter a value that corresponds to the XSD data type shown.

If you selected Supply Soap Envelope , enter or paste a well-formed and valid XML
document in the SOAP Request Envelope text area, starting with the <?xml
SOAP Request version="1.0"> declaration.
Envelope
If the service expects requests containing an array element or XML Page elements, a
skeleton document is provided as a starting point.

Viewing test coverage reports

Unit testing a Service MQ rule

Use the unit testing feature to verify that the operations of a Service MQ rule function correctly before you
add an external component to your testing process.

Important: Service MQ rules are no longer being actively developed. To avoid upgrade issues when these
rules are deprecated, use Service JMS rules instead. For more information about Service JMS rules, see
Service JMS rules.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard)
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
 Authentication
Field for the service requires authentication, enter the Operator ID to be used to test the
Description
User ID service

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only if the Message Data
Enter Request of the Request tab contains only scalar values, such as strings, numbers, or
Data Boolean values.

Invoke Initialization activity — A test activity creates values for the request
message values.

If you selected Specify individual request values for the previous field, enter in the
Message
Value field a literal constant value for each Header Field row on the Request tab. Enter
Header Values
a value that corresponds to the Java data type listed.

If you selected Specify individual request values for the previous field, enter in the
Message
Value field a literal constant value for each Message Data row listed on the Request
Buffer Values
tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity , enter here the Activity Name key part of
an activity that creates the information from a test MQ request message. The system
Activity assumes the Applies To class of the activity matches the Primary Page Class value on
the Service tab. If the activity applies to a different class, enter the class name, a
period, and the activity name.

Unit testing a Service SAP Rule

Services start their processing in response to a request from an external application. Before you add the
external application to your testing process, use the Simulate SOAP Service Execution feature to verify that
the service processes data appropriately. When using this feature, you manually provide some
representative data to process. You specify a test page for the rule to use, provide sample data as the
input, run the rule, and examine the results to see if they are what you expect.

Important: Service SAP rules are no longer being actively developed, and are being considered for
deprecation in upcoming releases. Using Service SAP rules does not follow Pega development best
practices. Use Service SOAP rules instead. For more information, see Service SOAP rules.

If you have the AutomatedTesting privilege (through an access role), you can use the features of
Automated Testing such as saved test cases and unit test suites for testing your Service SAP rule. See
About Automated Unit Testing and Working with the Test Cases tab for more information.

Before you begin

Before you begin testing the Service SAP rule, determine how you will provide the sample data for the
service rule to process. For help with this step, and for information about additional ways to test your
services, see the articles about testing services and connectors in the Testing Applications category of the
Pega Community.

Run the rule

Complete the following steps:

1. Save the rule.

2. Start the Tracer by clicking Actions > Trace. For more information, see Tracing services.
3. Click Actions > Run.
4. Fill out the fields in the form as described in the following table:
Field Description

If you have the AutomatedTesting privilege, Run Against a Saved Test Case ,
 Field Show Saved Results , and Run Test Case are available if this rule has saved test
Description
cases. To run the rule and see how its behavior compares to that in a previously
saved test case, select a choice from the Run Against a Saved Test Case drop-
down list.

After making your selection, click Run Test Case. If differences are found
Test Cases between the results of running the current state of the rule and the saved test
case, they are displayed and you have the options of choosing to ignore
differences for future test runs, overwriting the saved test case, and saving the
results. (See the Playing back saved test cases section in Working with the Test
Cases tab.)

Click Show Saved Results to view any previously saved test case results.

Select one of the following items to specify which requestor session to use in the
test:
Use current requestor context — Runs the rule in your session, that is, with
Requestor
your RuleSet list, privileges, and current clipboard.
Context
Initialize service requestor context — Run the rule in a newly created service
requestor session based on the APP requestor type and, if the service
package requires authentication, another Operator ID instance.

If you selected Initialize service requestor context , and the service package for
Authentication
the service requires authentication, enter the Operator ID to use to test the
User ID
service.

If you selected Initialize service requestor context , and the service package
Authentication
instance for the service requires authentication, enter a password for the
Password
Operator ID.

Select one of the following to define the source of request data values for this
test:
Specify individual request values — This option appears only when all
Enter Request
elements of the message are simple text values, not arrays or complex
Data
values of type XML Page.
Supply SOAP Envelope — You can enter an entire SOAP message including
the header.

If you selected Specify individual request values for the previous field, in the
SOAP Header
Value field, enter a literal constant value for each Header Field row on the
Values
Request tab. Enter a value that matches the XSD type shown.

SOAP If you selected Specify individual request values for the previous field, in the
Parameter Value field, enter a literal constant value for each Request Parameters row listed
Values on the Request tab. Enter a value that corresponds to the XSD data type shown.

If you selected Supply Soap Envelope , enter or paste a well-formed and valid XML
document in the SOAP Request Envelope text area, starting with the <?xml
SOAP Request version=“1.0” ?> declaration.
Envelope
If the service expects requests containing an array element or elements, a
skeleton document is provided as a starting point.

5. Click Execute to run the rule. The system runs the rule and displays the results.
6. Click the Clipboard icon in the Quick Launch area to see the clipboard pages that were generated.
7. Run the rule again using different data, as necessary.
8. Optional. If you have the AutomatedTesting privilege, the Save as Test Case button is available and
you can click it to create a Test Case that holds the test data and the results.

Viewing test coverage reports

Unit testing a Service SAPJCo rule

Use the unit testing feature to verify that the operations of a Service SAPJCo rule function correctly before
you add the external client to your testing process.
Important: Service SAPJCo rules are no longer being actively developed. To avoid upgrade issues when
these rules are deprecated, use other web-based SAP capabilities.

Unit testing provides only partial evidence of a correct implementation. For more comprehensive
information on testing services, see the Pega Community article Testing Services and Connectors.

Before you begin, see How to provide test data when testing service rules.

To run a unit test, complete the following steps:

1. Save the rule form.

2. Start the Tracer by clicking Actions Trace . For more information, see Tracing services.
3. Click Actions Run .
4. Complete the form as described in the following table, and then click Execute.

Field Description

Select a radio button to define the requestor session is to be used in the test:

Use current requestor context — Use your current requestor session (including
Requestor your RuleSet list, privileges, and current clipboard).
Context Initialize service requestor context — Create a new requestor session based on
the APP requestor type and, if the service package requires authentication,
another Operator ID instance.

If you selected Initialize service requestor context , and the service package instance
Authentication
for the service requires authentication, enter the Operator ID to be used to test the
User ID
service.

Authentication If you selected Initialize service requestor context , and the service package instance
Password for the service requires authentication, enter a password for the Operator ID.

Select a radio button to define the source of request data values for this test:

Specify individual request values — This option appears only if the Java method
Enter Request parameters are scalar values, such as strings, numbers, or booleans.
Data
Invoke Initialization activity — A test activity creates values for the Java method
values.

Method If you selected Specify individual request values for the previous field, enter in the
Parameter Value field a literal constant value for each Java method parameter declared on the
Values Parameters tab. Enter a value that corresponds to the Java data type listed.

If you selected Invoke Initialization activity, enter here the Activity Name key part of an
activity that creates Java method parameters. The system assumes the Applies To
Activity class of the activity matches the Primary Page Class value on the Service tab. If the
activity applies to a different class, enter the class name, a period, and the activity
name.

Viewing test coverage reports

Unit testing a Service SOAP rule

Services start their processing in response to a request from an external application. Before you add the
external application to your testing process, use the Simulate SOAP Service Execution feature to verify that
the service processes data appropriately. When using this feature, you manually provide some
representative data to process. You specify a test page for the rule to use, provide sample data as the
input, run the rule, and examine the results to see if they are what you expect.

If you have the AutomatedTesting privilege (through an access role), you can use the features of
Automated Testing such as saved test cases and unit test suites for testing your Service SOAP rule. See
About Automated Unit Testing and Working with the Test Cases tab for more information.

Before you begin

Before you begin testing the Service SOAP rule, determine how you will provide the sample data for the
service rule to process. For help with this step, and for information about additional ways to test your
services, see the articles about testing services and connectors in the Testing Applications category of the
Pega Community.

Run the rule

Complete the following steps:

1. Save the rule.

2. Start the Tracer by clicking Actions > Trace. For more information, see Tracing services.
3. Click Actions > Run.
4. Fill out the fields in the form as described in the following table:
Field Description

If you have the AutomatedTesting privilege, Run Against a Saved Test Case, Show
Saved Results, and Run Test Case are available if this rule has saved test cases.
To run the rule and see how its behavior compares to that in a previously saved
test case, select a choice from the Run Against a Saved Test Case drop-down list.

After making your selection, click Run Test Case. If differences are found
Test Cases between the results of running the current state of the rule and the saved test
case, they are displayed and you have the options of choosing to ignore
differences for future test runs, overwriting the saved test case, and saving the
results. (See the Playing back saved test cases section in Working with the Test
Cases tab.)

Click Show Saved Results to view any previously saved test case results.

Select one of the following items to specify which requestor session to use in the
test:
Use current requestor context -- Runs the rule in your session, that is, with
Requestor
your RuleSet list, privileges, and current clipboard.
Context
Initialize service requestor context -- Run the rule in a newly created service
requestor session based on the APP requestor type and, if the service
package requires authentication, another Operator ID instance.

If you selected Initialize service requestor context, and the service package for
Authentication
the service requires authentication, enter the Operator ID to use to test the
User ID
service.

If you selected Initialize service requestor context, and the service package
Authentication
instance for the service requires authentication, enter a password for the
Password
Operator ID.

Select one of the following to define the source of request data values for this
test:
Specify individual request values -- This option appears only when all
Enter Request
elements of the message are simple text values, not arrays or complex
Data
values of type XML Page.
Supply SOAP Envelope -- You can enter an entire SOAP message including
the header.

If you selected Specify individual request values for the previous field, in the
SOAP Header
Value field, enter a literal constant value for each Header Field row on the
Values
Request tab. Enter a value that matches the XSD type shown.

SOAP If you selected Specify individual request values for the previous field, in the
Parameter Value field, enter a literal constant value for each Request Parameters row listed
 Values
Field on the Request tab. Enter a value that corresponds to the XSD data type shown.
Description
If you selected Supply Soap Envelope, enter or paste a well-formed and valid XML
document in the SOAP Request Envelope text area, starting with the <?xml
SOAP Request version=“1.0” ?> declaration.
Envelope
If the service expects requests containing an array element or XML Page
elements, a skeleton document is provided as a starting point.

5. Click Execute to run the rule. The system runs the rule and displays the results.
6. Click the Clipboard icon in the Quick Launch area to see the clipboard pages that were generated.
7. Run the rule again using different data, as necessary.
8. Optional. If you have the AutomatedTesting privilege, the Save as Test Case button is available and
you can click it to create a Test Case that holds the test data and the results.

Service SOAP rules

Creating a Service SOAP rule
WSDL generation for Service SOAP rules

Viewing clipboard pages created by unit testing a rule

After running a rule, you can open the Clipboard tool and examine the output as it appears on the resulting
clipboard pages.

The following clipboard pages are created when you unit test a rule:

RuleToRun — The clipboard representation of the rule that you tested.

runRulePage — Holds the output from the rule.
temp_ pages — Pages created or copied by the Run Rule feature when it ran the rule. The names of
these pages begin with the literal temp_.
pySimulationDataPage — For service rules, a page of the helper class Data-Admin-IS-ClientSimulation.
Contains information about the simulated request and response.

Unit testing individual rules

Engaging with stakeholders to define a Microjourney

To ensure that your Microjourney meets all customer needs, engage your stakeholders in the application
development process. When you clearly communicate with the other parties that are engaged in your
projects, you can fully understand the requirements of your clients, and then provide effective solutions.

Adopting feature-driven development

Develop capabilities in the context of a feature to maintain functional requirements and project status
directly in your application.

Documenting your application

Create documentation to engage stakeholders and give guidance to the end users and developers who
interact with your application. You can generate a physical document or provide embedded
information, based on your audience.

Understanding project roles and personas

Creating a Microjourney for customer success

Adopting feature-driven development

Develop capabilities in the context of a feature to maintain functional requirements and project status
directly in your application.

Before you begin: Ensure that you have the PegaRULES:AgileWorkbench access role and the
pxAgileWorkbench privilege. As a best practice, use Agile Workbench to manage feature-driven
development because work items provide traceability from features to the rules that support them.

1. Feature order
 To understand the importance of the features in your application, look at the order in which your
application lists features. Your application lists features in order of relevance to the current
implementation, with the oldest features at the top by default.

2. Creating features

Ensure that your application supports capabilities that meet your specific business needs and
customer expectations, by creating features. When you create features, you communicate what
elements your development team needs to implement to deliver a complete application, so that you
can appropriately plan your work and inform stakeholders about your application design.

3. Creating subfeatures

Provide more advanced and varied solutions in your application by enhancing application features with
subfeatures. Create a subfeature to define a capability that extends another capability.

4. Tracking feature-driven development

Create and manage stories to track the progress of your feature-driven development.

5. Collaborating with development teams

Improve and accelerate your project delivery by collaborating with development teams. When you
post Pulse messages, you ensure that team members have up-to-date and relevant information about
the features that they work on.

6. Integrating Agile Workbench with Jira in Pega Platform from 8.3.x

Capture real-time feedback about an application development project directly in the application with
the Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace,
you can continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take
advantage of its project management features, such as project and issue tracking, Scrum and Kanban
support, backlog prioritization, and sprint planning.

7. Integrating Agile Workbench with Jira in Pega Platform 8.1.x to 8.2.x

Capture real-time feedback about an application development project directly in the application with
the Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace,
you can continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take
advantage of its project management features, such as project and issue tracking, Scrum and Kanban
support, backlog prioritization, and sprint planning.

8. Integrating Agile Workbench with Jira in Pega Platform 7.3.x to 7.4.x

Capture real-time feedback about an application development project directly in the application with
the Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace,
you can continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take
advantage of its project management features, such as project and issue tracking, Scrum and Kanban
support, backlog prioritization, and sprint planning.

9. Creating a specification

Defining and creating specifications for an application is an iterative process that requires input from
all stakeholders. If the information about a specification is detailed and up-to-date, the specification is
more useful during the application development process.

Managing application features

Feature order
To understand the importance of the features in your application, look at the order in which your
application lists features. Your application lists features in order of relevance to the current implementation,
with the oldest features at the top by default.

When you update an application, it retains the features from previous versions of the application, as well as
from built-on applications. You can reorder features from previous or built-on applications in your current
version, which by default your application lists in the following order:

1. Features from the current version of your application: from the oldest to the newest.
2. Features from earlier versions of your application: based on the order of features in those versions.
3. Features from built-on applications: based on the order of features in those applications.

If you have multiple built-on applications, the features follow the order from the built-on application
stacks.

To override the default order and emphasize the features that are most important in the current version of
your application, you can manually reorder features.

When you reorder the features in either an earlier version of your application or a built-on application, the
current version of your application also reflects the changes, unless you customize the default order in the
current version.

When you reorder the features in the current version of your application, the new order overrides any other
changes that you make to feature order in earlier versions of your application or built-on applications.

You can also reset a custom feature order, back to the default order.

Associating a feature with a work item

Creating stories
Creating bugs to report feature defects
Requesting feature enhancements

Creating features
Ensure that your application supports capabilities that meet your specific business needs and customer
expectations, by creating features. When you create features, you communicate what elements your
development team needs to implement to deliver a complete application, so that you can appropriately
plan your work and inform stakeholders about your application design.

For example, you can create features that represent language packs and case types to ensure that you
deliver an application that meets the requirements defined with your stakeholders. During application
development, your team turns features into usable functionalities.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Application profile workspace, click the Feature map tab.
4. In the header of the Features section, click the Create icon.
5. In the Name field, enter text that uniquely identifies the feature.
6. In the Description field, enter text that describes the business value for this feature and provides an
overview of what users can do when the development team implements the feature.
7. Click Create.

What to do next: Extend the capability with additional capabilities by creating subfeatures. For more
information, see Creating subfeatures.

Deleting a feature

Creating subfeatures
Provide more advanced and varied solutions in your application by enhancing application features with
subfeatures. Create a subfeature to define a capability that extends another capability.

For example, you can create a feature that describes reporting and monitoring, and then extend that
feature with subfeatures for business reporting and analytics monitoring.
Before you begin: Create a main feature that you want to expand. For more information, see Creating
features.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Application profile workspace, click the Feature map tab.
4. In the Features section, click the name of the feature that you want to supplement with a subfeature.
 5. In the Subfeatures section, click the Create icon.
6. In the Name field, enter text that uniquely identifies the subfeature.
7. In the Description field, enter text that describes the business value for this subfeature and provides
an overview of what users can do when the development team implements this subfeature.
8. Click Create.

What to do next: Extend the subfeature with additional capabilities by creating additional nested
subfeatures. You can create four levels of subfeatures.

Deleting a feature

Managing application features

Actively manage and document the features that you implement to provide traceability to future
developers who extend your application.

The following tasks can help you manage features:

Reviewing application features

Review the current features in your application so that you can make informed decisions about the
new features and subfeatures that you create. To access more information about your features, review
them by switching to a tree view.

Changing feature levels

Change the relative position of a feature in the hierarchy to support their reuse and extension in other
applications. The feature order and the relationships between features and subfeatures reflect how
important features are and how different features correlate with each other.

Associating rules with features

Document which rules implement a feature to improve the traceability and extensibility of your
application. When you associate a feature with a rule, you can conveniently check which elements
exactly build your application so that you can make informed decisions when you decide to reuse a
feature in another application.

Associating a feature with a work item

Associate your assigned work items with the features that they implement to improve traceability in
your application.

Skimming features to the latest version

Copy, or skim, features from previous versions of your application to ensure that the application that
you ship includes the complete feature hierarchy.

Deleting a feature

Delete features when they are unused or no longer relevant.

Creating features
Creating subfeatures

Reviewing application features

Review the current features in your application so that you can make informed decisions about the new
features and subfeatures that you create. To access more information about your features, review them by
switching to a tree view.

For example, by using a tree view you can view the stories, bugs, and feedback items associated with a
feature, so that you can plan your work accordingly and ensure that you deliver an application that meets
all your business requirements. You can also check whether a feature belongs to your current or built-on
application.

1. In the navigation pane of App Studio, click Overview.

 2. In the Application profile workspace, click Manage.
3. In the Application profile workspace, click Feature map.
4. In the Features section, click the Switch to tree view icon.
5. Expand the list of features, and then review the subfeatures that extend your features.
6. In the Version column, review the application type to understand which features are unique to your
application and which features you inherit from other built-on applications or versions.
7. Optional: To get the status of a feature, analyze the progress bar in the Progress column.
8. Optional: To open items associated with the feature in the Agile Workbench tool, in the Progress
column, click a relevant icon.

Creating features
Managing application inventory
Estimating application development

Changing feature levels

Change the relative position of a feature in the hierarchy to support their reuse and extension in other
applications. The feature order and the relationships between features and subfeatures reflect how
important features are and how different features correlate with each other.

Before you begin: Learn how a feature order corresponds with significance of different features. For more
information, see Feature order.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Application profile workspace, click Feature map.
4. In the Features section, click the Switch to tree view icon.
5. Review the different levels in your feature hierarchy by expanding the list of features and subfeatures.
6. Change the feature position:
To move a feature up or down in the feature list, drag the item into a new position.
To turn a feature into a subfeature, drag the feature over the top-level feature.

Creating features
Creating subfeatures

Requesting feature enhancements

Improve and adjust an application to your specific business needs by requesting a feature enhancement.
You request an enhancement by creating a feedback item. Your development team triages feedback items
and decides whether to implement or reject the enhancement, based on priority and available resources.

Before you begin: To provide context for the team and to speed up feature development through videos
or screenshots, log in to your application in Google Chrome by using the HTTPS protocol.

1. In the header of App Studio, click the Agile Workbench icon.

2. Optional: To record a video or take screenshots, in the Agile Workbench tool, add the Pega Screen
and Video Capture extension to your browser by clicking Install the plugin at the bottom of the
tool, and then following the instructions in Google Chrome.
3. In the header of the Agile Workbench tool, click Create work item Create Feedback .
4. In the Name field, enter text that summarizes the change.
5. In the Description field, enter text that includes the rationale for the change and details, such as use
cases or metrics, that can help the team decide how to triage the feedback.
6. In the Associated feature list, select a feature that relates to the enhancement.
7. In the Priority field, select the relative importance of the enhancement.
During triaging the development team uses this field to determine when they implement the feedback
relative to other items in the product backlog.
8. Optional: To add an attachment, click Add attachment, and then select the attachment type:
Choices Actions

a. On the Attachments menu, click Record video.

Record a b. In the Share your screen window, select a screen that you want to record, and
video then begin the recording by clicking Share.
c. In the timer window, stop the recording by clicking Stop.
 Choices a. On the Attachments menu, click Capture screen.
Actions
b. Drag the target pointer onto the screen area that relates to the feature
Take a enhancement.
screenshot c. In the text field below the target pointer, enter additional information about the
bug, and then click Capture screen.
d. In the Share your entire screen window, select a screen that you want to
capture, and click Share.

a. On the Attachments menu, click Attach files.

Attach a
b. In the Attach file(s) window, select the files that you want to upload, and then
file
click Attach.

a. On the Attachments menu, click Attach URL.

b. In the Attach a link window, in the Name field, enter a descriptive name for a
Attach a URL.
URL c. In the URL field, enter the URL.
d. In the Attachment category list, select URL.
e. Click Submit.
9. Click Save.

What to do next: Discuss the feedback item with a development team. For more information, see
Collaborating with development teams.

Creating bugs to report feature defects

Triaging a feedback item

Creating bugs to report feature defects

Improve your application by identifying any issues that might have a negative impact and creating bugs
that report feature defects. When you create bugs, your development team can track the defects, and then
fix the issues to deliver an effective product.

Before you begin: To provide context for the team and to speed up feature development through videos
or screenshots, log in to your application in Google Chrome by using the HTTPS protocol.

1. In the header of App Studio, click the Agile Workbench icon.

2. Optional: To record a video or take screenshots, in the Agile Workbench tool, add the Pega Screen
and Video Capture extension to your browser by clicking Install the plugin at the bottom of the
tool, and then following the instructions in Google Chrome.
3. In the header of the Agile Workbench tool, click Create work item Create bug .
4. In the Name field, enter text that summarizes the issue.
5. In the Description field, enter text that includes steps to reproduce the bug, and any supporting
information. For example: You can provide the credentials to your application, which can help the
team fix the bug more quickly.
6. In the Associated feature list, select a feature that relates to the bug.
7. In the Due field, select a deadline for bug resolution.
8. In the Severity field, click an option that indicates the extent to which the bug affects your
application.
9. Optional: To speed up bug resolution, in the Owner field, assign the bug to a user by entering a user
ID.
10. Optional: To add an attachment, click Add attachment, and then select the attachment type:
Choices Actions

a. On the Attachments menu, click Record video.

Record a b. In the Share your screen window, select a screen that you want to record, and
video then begin the recording by clicking Share.
c. In the timer window, stop the recording by clicking Stop.

a. On the Attachments menu, click Capture screen.

b. Drag the target pointer onto the screen area that shows the bug.
Take a c. In the text field below the target pointer, enter additional information about the
screenshot bug, and then click Capture screen.
d. In the Share your entire screen window, select a screen that you want to
capture, and click Share.
 Choices a. On the Attachments menu, click Attach files.
Actions
Attach a
b. In the Attach file(s) window, select the files that you want to upload, and then
file
click Attach.

a. On the Attachments menu, click Attach URL.

b. In the Attach a link window, in the Name field, enter a descriptive name for a
Attach a URL.
URL c. In the URL field, enter the URL.
d. In the Attachment category list, select URL.
e. Click Submit.
11. Click Save.

What to do next: Discuss the bug with a development team. For more information, see Collaborating with
development teams.

Requesting feature enhancements

Triaging a feedback item

Actively triage feedback items to create relevant work items that you can track to closure.

1. In the header of App Studio, click the Agile Workbench icon.

2. Click Feedback to view a list of feedback items.
3. Click the name of a feedback item.
4. In the Description field, review the requested feature enhancement.
5. Consult your product owner to determine whether to implement the enhancement.
6. Click Mark as..., and then select an option, based on your decision.
New story - The enhancement requires functional changes that you can break down into tasks.
New bug - The enhancement is a small issue or defect.
Rejected - The enhancement is irrelevant or out of scope.
7. Provide details in the work item that you create from the feedback item. For more information, see:

Creating bugs to report feature defects

Creating stories

8. Click Save.

Result:

If Agile Workbench is integrated with Pega Agile Studio, the stories and bugs are synchronized with Pega
Agile Studio.

Requesting feature enhancements

Associating a feature with a work item

Associating rules with features

Document which rules implement a feature to improve the traceability and extensibility of your application.
When you associate a feature with a rule, you can conveniently check which elements exactly build your
application so that you can make informed decisions when you decide to reuse a feature in another
application.

For example, you can associate a feature that represents your business process template for reviewing loan
requests with rules that define a case type, a service-level agreement, and an email message. As a result,
you get a holistic view of the elements that build your feature.

1. In the header of Dev Studio, click the name of the application, and then click Overview.
2. In the Features section, click the name of a feature.
3. On the Associated rules tab, click Add rule.
4. In the Type field, press the Down arrow key, and then select a rule type to narrow the list of rules that
you can select. For example: Select Case Type.
5. In the Name field, press the Down arrow key, and then select the rule that you want to associate with
the feature. For example: Select Review loan request .
 Tip: To narrow the list of results and help you decide which rule to choose when more than one rule
has the same name, you can enter a class name in the Applies to field. Otherwise, the system
autpopulates the Applies to field.

Result: Your application manages the links among features and rules as the development process
advances. When you create a rule by copying or specializing another rule, your application copies the links
from the original rule to features of the new rule. For example, when you associate a Language pack
feature with a Loan request case type rule, and then copy the Loan request case type rule, your application
automatically copies the link between the Language pack feature and the new case type rule. When you
delete, withdraw, or block a rule, your application removes the links from features.

Reviewing application features

Creating a rule
Creating a rule specialized by circumstance

Associating a feature with a work item

Associate your assigned work items with the features that they implement to improve traceability in your
application.

1. In the header of App Studio, click the Agile Workbench icon.

2. In the header of the Agile Workbench tool, click the type of work item that you are implementing.
3. Click a work item in the list to open it.
Tip: To quickly find a work item in a long list, use the search tool, sort the list, or filter the list by
feature.
4. Click the Associated feature list.
5. Click the feature that you want to associate with the work item, and then click Select.
6. Click Save.

Result: If the feature that you choose is not in your current application version, the feature is promoted to
your current application version.

Creating features
Creating stories
Creating bugs to report feature defects
Requesting feature enhancements

Skimming features to the latest version

Copy, or skim, features from previous versions of your application to ensure that the application that you
ship includes the complete feature hierarchy.

1. Log in to the latest version of your application.

2. In the header of Dev Studio, click the name of the application, and then click Overview.
3. In the Features section, click the Switch to tree view icon.
4. In the Features section, click Actions Skim previous features .
5. Click Yes, skim features.
6. In the Version column, verify that all features are associated with your current application.

Creating features
Creating subfeatures

Deleting a feature
Delete features when they are unused or no longer relevant.

Before you begin: Ensure that your feature does not have any of the following characteristics:

Inherited from a built-on application

Defined in a previous version of your application

Associated with open work items

 Contains subfeatures that are defined in your current application

In these scenarios, an option to delete a feature is unavailable.

1. In the header of App Studio, click the Agile Workbench icon.

2. In the header of Agile Workbench, click the More icon, and then click Application Profile.
3. In the Features section, click the Switch to tree view icon.
4. Expand the list of features and subfeatures to find the feature to delete.
5. Click the Delete icon.

Creating features
Creating subfeatures
Associating a feature with a work item

Tracking feature-driven development

Create and manage stories to track the progress of your feature-driven development.

1. Create stories that capture functional requirements.

Tip: To create stories in bulk, use a story template.
2. Work with your development team to determine which story to implement, based on project status
and priorities.
3. Set your current work item to the story ID.
4. Change the story status to Doing.
5. Follow the instructions in the story to create the required logic, data, or interface elements in your
application.
6. Change the story status to Done.

Agile Workbench

Agile Workbench is a tool for project stakeholders that captures real-time feedback about your
application and tracks feature development. By managing feedback and development status directly
in your application, you can make application development more efficient.

Implementation methodologies

An implementation methodology is an adaptable process framework for managing an application

development project. When you align your organization's approach to project management with an
implementation methodology, you can quickly define and implement the objectives of your
application.

Integrating Agile Workbench with Pega Agile Studio

Integrate Agile Workbench with Pega Agile Studio to synchronize stories and bugs between the two
systems.

Changing statuses of work items

Managing application features

Agile Workbench
Agile Workbench is a tool for project stakeholders that captures real-time feedback about your application
and tracks feature development. By managing feedback and development status directly in your
application, you can make application development more efficient.

You provide feedback by creating a work item that is a user story, a bug, or a feedback item. Your
feedback can contain videos, annotated screen captures, file attachments, or URLs. Project stakeholders
can view, update, and triage the work items that you create. When you use Agile Workbench to create
features, you can associate each feature with a work item to establish traceability from requirement to
implementation. You can also configure Agile Workbench to integrate with Pega Agile Studio so that bugs
and stories are synchronized between the two systems.

Integrating Agile Workbench with Pega Agile Studio

Setting your current work item
Adopting feature-driven development
Implementation methodologies
An implementation methodology is an adaptable process framework for managing an application
development project. When you align your organization's approach to project management with an
implementation methodology, you can quickly define and implement the objectives of your application.

You reference an implementation methodology in capabilities, such as application and specification rules,
the New Application wizard, the Sizing wizard and project sizing tool, and the Document Application tool.

Scrum
The Scrum methodology takes an agile approach to development that accomplishes iterations in short
cycles called sprints. When you follow this methodology, you create a product backlog that captures the
planned functionality, corresponding business value, and sprint time lines for your application.

You can use Pega Agile Studio and the Agile Workbench tool to synchronize your product backlog with the
bugs and stories that your team creates during application development.

Iterative Waterfall
The Iterative Waterfall methodology takes an iterative approach to development that uses the following
phases: Business Value Assessment (BVA), Conception, Elaboration, Construction, and Transition.

Because the phases in this methodology are flexible, you can adapt Iterative Waterfall to fit projects of any
size.

Specifications in Iterative Waterfall are commonly called use cases.

Integrating Agile Workbench with Pega Agile Studio

Integrating Agile Workbench with Pega Agile Studio

Integrate Agile Workbench with Pega Agile Studio to synchronize stories and bugs between the two
systems.

Before you do this task, verify that your operator preferences provide a valid user ID for Pega Agile Studio.
On the Operator menu, click Preferences, and update the user ID in the Project management section.

1. In the Dev Studio header, click the name of your current application, and click Definition.
2. On the Integration & security tab, in the Agile Workbench integration section, click Configure
integration.
3. Select Pega Agile Studio.
4. Provide the API URL for Pega Agile Studio, and click Connect.
Note: To disconnect an existing integration, click Disconnect Integration.
5. Associate your Agile Workbench work items with a product and release by selecting an existing Pega
Agile Studio product and release, or by creating a product and release
6. Click Begin integration.
7. Click Done after the integration is complete.

What to do next: On Pega Community, Pega Exchange provides components that you can download and
install to support integration with other project management tools, such as JIRA and CA Agile Central.

Agile Workbench
Setting your current work item
Adopting feature-driven development

Creating stories
Speed up your application development by providing your team with specific information about the
features that they design. By implementing stories, you can also track and manage the workload of your
team more effectively.

When you create stories, you define the functional requirements for features, estimate the completion time,
and assign the priority level.
Before you begin: To provide context for the team and to speed up feature development through videos
or screenshots, log in to your application in Google Chrome by using the HTTPS protocol.

1. In the header of App Studio, click the Agile Workbench icon.

2. Optional: To record videos or take screenshots, in the Agile Workbench tool, add the Pega Screen
and Video Capture extension to your browser, by clicking Install the plugin at the bottom of the
tool, and then following the instructions in Google Chrome.
3. In the header of the Agile Workbench tool, click Create work item Create Story .
4. In the Name field, enter text that summarizes what users can do with the new functionality.
5. In the Description field, enter text that describes the new functionality to implement, the key
stakeholders to involve, and the relevant business value.
6. In the Associated feature list, select a feature that relates to the story.
7. In the Due field, select a deadline for story resolution.
8. Optional: To speed up story resolution, in the Owner field, assign the story to a user by entering a
user ID.
9. In the Complexity list, select the level of effort to complete the story.
10. In the Priority field, select the relative importance of the story.
During triaging, the development team uses this field to determine when to implement the story
relative to other items in the product backlog.
11. Optional: To add an attachment, click Add attachment, and then select the attachment type:
Choices Actions

a. On the Attachments menu, click Record video.

Record a b. In the Share your screen window, select a screen that you want to record, and
video then begin the recording by clicking Share.
c. In the timer window, stop the recording by clicking Stop.

a. On the Attachments menu, click Capture screen.

b. Drag the target pointer onto the screen area that relates to the story.
Take a c. In the text field below the target pointer, enter additional information about the
screenshot story, and then click Capture screen.
d. In the Share your entire screen window, select a screen that you want to
capture, and then click Share.

a. On the Attachments menu, click Attach files.

Attach a
b. In the Attach file(s) window, select the files that you want to upload, and then
file
click Attach.

a. On the Attachments menu, click Attach URL.

b. In the Attach a link window, in the Name field, enter a descriptive name for the
Attach a URL.
URL c. In the URL field, enter the URL.
d. In the Attachment category list, select URL.
e. Click Submit.
12. In the Acceptance criteria section, click Add new criteria, and then enter metrics or constraints
that the team must meet before they can resolve the story.
13. Click Save.

What to do next: Discuss the story with a development team. For more information, see Collaborating
with development teams.

Creating stories in bulk

Creating stories in bulk

Create stories in bulk to save time developing features.

Before you begin: Ensure that your application is not integrated with Pega Agile Studio or other project
management applications.

1. Populating story templates

Automate the creation of stories by populating the columns in a story template with functional
 requirements. By implementing stories, you can track, manage, and communicate development of
your projects. For example, you can define which stories contain features that are essential to your
application, so that your development team can prioritize their work.

2. Importing story templates

Track and manage development of your application by importing stories into Agile Workbench. By
importing stories into your project you can ensure that your development team correctly prioritizes
work, for example, by focusing on stories with a high priority.

Creating stories
Exporting stories
Troubleshooting errors with a story template

Populating story templates

Automate the creation of stories by populating the columns in a story template with functional
requirements. By implementing stories, you can track, manage, and communicate development of your
projects. For example, you can define which stories contain features that are essential to your application,
so that your development team can prioritize their work.

1. Download a story template:

a. In the header of App Studio, click the Agile Workbench icon.
b. In the header of Agile Workbench, click the More icon, and then click Application Profile.
c. At the top of the project overview, click Actions Import stories .
d. In the Import stories window, download a Microsoft Excel story template file to your local
computer by clicking Download the template.
e. Open the file.
2. In the Name column, enter text that summarizes what users can do with the functionality that the
story delivers.

If you enter duplicate names, your application creates stories with the same name but different IDs.

3. Optional: Add supporting information to the story:

a. In the Description column, enter text that describes the new functionality to implement, the key
stakeholders to involve, and the relevant business value.
b. In the Associated feature ID column, enter the ID of the feature that this story implements.

For more information about feature IDs, see Finding a feature ID.

Result: During import, your application promotes features from the built-on application or
previous versions, to the current version of your application.
c. In the Complexity column, select an option to indicate the level of effort that is needed to
complete the story.
d. In the Priority column, select the importance of the story, relative to other stories in the product
backlog, to indicate appropriate time for the team to start work on the story.
e. In the Acceptance criteria column, enter specific metrics or constraints to consider before the
team can resolve the story.
f. Optional: To define more than one criterion, press the Alt and Enter keys to insert a line break in
the cell, and then repeat substep 3.e.
4. Save and close the file, without changing the file format.

What to do next: Import a story template into Agile Workbench. For more information, see Importing
story templates.

Finding a feature ID
Creating stories in bulk
Troubleshooting errors with a story template
Project sizing

Importing story templates

Track and manage development of your application by importing stories into Agile Workbench. By
importing stories into your project you can ensure that your development team correctly prioritizes work,
for example, by focusing on stories with a high priority.
Before you begin: Create a story template. For more information, see Populating story templates.

1. In the header of App Studio, click the Agile Workbench icon.

2. In the header of Agile Workbench, click the More icon, and then click Application Profile.
3. At the top of the project overview, click Actions Import stories .
4. In the Import stories window, select a story template to upload by clicking Choose File.
5. Upload the story template by navigating to the location of the file, and then clicking Open.
6. Click Import. Result: The stories that you imported are visible in Agile Workbench, in the Stories
tab.

Exporting stories
Troubleshooting errors with a story template

Finding a feature ID
Find the ID of a feature so that you can reference it later in a story or story template.

1. In the navigation panel, click App to open the Application Explorer.

2. Click the Classes tab.
3. In the search field, enter Data-Application-.
4. Click Feature to display a list of features.
5. In the Application name column, click the Filter icon, and then enter the name of your application or
a built-on application to narrow the results.
6. Copy the relevant values in the Feature ID column so that you can add them to the Associated
feature ID column in your story template.

Populating story templates

Creating stories in bulk
Managing application features

Troubleshooting errors with a story template

Errors may occur when you create stories in bulk. Use the following guidance to resolve issues with the
story templates that you import to Agile Workbench.

The template has an invalid file structure or an invalid file type.

a. In the Import Stories dialog box, click Download the template to save a Microsoft Excel file to
your local machine.
b. Open the file.
c. Copy the information from your original template to the relevant columns in the file.
d. Save the file but do not change its format.
e. In the Import Stories dialog box, click Choose File.
f. Navigate to the location of your story template, and then click Open to upload the file.
g. Click Import.
Stories in the template fail validation.
a. Open your story template.
b. Ensure that all stories provide a value in the Name column.
c. Save the file but do not change its format.
d. Restart the import.

Importing story templates

Creating stories in bulk

Exporting stories
Export stories to quickly share information with project stakeholders.

1. In the header of App Studio, click the Agile Workbench icon.

2. In the header of Agile Workbench, click the More icon, and then click Application Profile.
3. Click Actions Export Stories .

Result: A Microsoft Excel file is saved to your local machine.

Importing story templates

 Agile Workbench

Setting your current work item

Control which work item is associated with rules that you create, edit, or copy by setting your current work
item each time that you start a new task.

Note: If Agile Workbench is integrated with Pega Agile Studio, you can view development changes on the
Related updates tab of a work item.

1. In the developer toolbar, click Current work.

2. In the What are you currently working on field, press the Down Arrow key, and then select the
work item that you are implementing.
3. Click Submit.

Adopting feature-driven development

Changing statuses of work items

Provide accurate status updates to work items to help your team understand how much work implementing
a feature still requires.

For example, when your team starts working on a story, you can drag the story from the To do column to
the Doing column.

1. In the header of App Studio, click the Agile Workbench icon.

2. In the header of the Agile Workbench tool, click More Overview .
3. In the Work items section, change the status of a work item by dragging the item to a different
column.
4. Optional: To quickly find an item that you want to update, filter the stories:
a. In the header of the Work items section, click All.
b. In the list, select the items that you want to display.

Associating a feature with a work item

Agile Workbench

Collaborating with development teams

Improve and accelerate your project delivery by collaborating with development teams. When you post
Pulse messages, you ensure that team members have up-to-date and relevant information about the
features that they work on.

You can post general messages that users see in the Developer collaboration section, and comment on
specific work items, such as stories and bugs in Agile Workbench. You can also filter, comment, and like
messages.

1. In the header of App Studio, choose the context for your message:
To post a general message, click the Toggle developer collaboration icon.
To comment on a work item, such as a user story, a bug, or a feedback item, click the Toggle
Agile Workbench icon, and then in the list select an item that you want to discuss.
2. In the Post text field, enter your message.
3. Optional: To provide more information and context to your message, add an attachment:
a. Below the text field, click the Add attachment icon.
b. In the dialog box that appears, select a local file that you want to attach.
c. Attach the file to the message by clicking Open.
4. Optional: To emphasize specific information in your message, format your text by clicking the
Formatting help icon, and then copying special characters into the message. For example: You can
write a part of your message in bold or italics.
5. Optional: To provide only relevant information for the users, make your post visible only to specific
users:
a. Above the text field, click Post Private message .
b. In the Add users field, enter or select IDs of the users that you want to be able to see the post.
By default, everyone in the application can view posts.
6. Click Post.
 Collaborating with users by using Pulse
Replying to a message in Pulse

Integrating Agile Workbench with Jira in Pega Platform from

8.3.x
Capture real-time feedback about an application development project directly in the application with the
Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace, you can
continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take advantage of
its project management features, such as project and issue tracking, Scrum and Kanban support, backlog
prioritization, and sprint planning.

Before you begin: Prepare for the integrating Agile Workbench with Jira:

Disconnect any existing integration to a project management system. On the Integration & security
tab of the Application rule form, in the Agile Workbench integration section, click Configure
integration, and then click Disconnect integration.
If you use a custom workflow or a custom list of priorities in Jira, ensure that Jira workflow and
priorities match the Agile Workbench configuration. For more information, see Mappings of Agile
Workbench values to Jira values.
Check whether your Jira version is complaint with General Data Protection Regulation (GDPR). For
more information, refer to Atlassian documentation.

1. Download the Jira component from the Marketplace.

2. In the header of Dev Studio, click the name of the application, and then click Definition.
3. On the Definition tab, in the Enabled components section, click Manage components.
4. Click Install new, select the file that you downloaded from the Marketplace, and then click Open.
5. Enable this component for your application by selecting the Enabled check box, and then click OK.
6. In the list of enabled components, verify the Jira component and its version, and then save the rule
form by clicking Save.
7. Update the PM_Jira_AuthProfile Authentication Profile instance with credentials that you plan to use to
access your Jira system through REST authentication:
Provide the user ID as user name and the API token for password. If your Jira server does not
support API token, use your Jira password.

For more information about Jira API token, refer to the Atlassian documentation.

To use a method of authentication other than Basic, delete and re-add the PM_Jira_AuthProfile
instance by using the same name for the new version.
8. In the authentication profile, select the Preemptive authentication check box.
9. In the navigation pane of Dev Studio, click your operator icon, and then click Preferences.
10. In the Project management section, in the User ID field, enter your Jira details:
To integrate with Jira version that is GDPR-complaint, enter your Jira account ID.
To integrate with Jira version that is GDPR non-complaint, enter your Jira user ID.
11. Click Save.
12. If your Jira version is GDPR non-compliant, perform additional configurations to integrate:
a. Expand the SysAdmin category, and then click RuleSet.
b. Click the JiraIntegration ruleset, and then open the IsAccountIDSupportedByJIRA rule.
c. Click Save Save as .
For more information about saving rules, see Copying a rule or data instance.
d. On the Advanced tab of the new rule, set the When rule name to Never, and then click Save.
e. Perform check-in.
For more information about checking in rules, see Checking in a rule.
13. In the header of Dev Studio, click the name of the application, and then click Definition.
14. On the Integration & security tab of the Application rule form, in the Agile Workbench
integration section, click Configure integration.
15. Select Jira.
16. Provide the API URL for Jira, and then click Connect.
17. Associate your Agile Workbench work items with a project and release by selecting an existing Jira
project and release, or by creating a project and release.
18. Click Begin integration. Result: All of the user stories and bugs that were created in Agile
Workbench are exported to Jira and associated with the project and release that you specified. A
confirmation message explains the results of the integration process.
19. Click Done.
 Documenting your application
Building your first application

Integrating Agile Workbench with Jira in Pega Platform 8.1.x to

8.2.x
Capture real-time feedback about an application development project directly in the application with the
Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace, you can
continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take advantage of
its project management features, such as project and issue tracking, Scrum and Kanban support, backlog
prioritization, and sprint planning.

Before you begin: Prepare for the integrating Agile Workbench with Jira:

Disconnect any existing integration to a project management system. On the Integration & security
tab of the Application rule form, in the Agile Workbench integration section, click Configure
integration, and then click Disconnect integration.
Check whether your Jira version is complaint with General Data Protection Regulation (GDPR). For
more information refer to Atlassian documentation.

1. Download the Jira component from the Marketplace.

2. In the header of Dev Studio, click the name of the application, and then click Definition.
3. On the Definition tab, in the Enabled components section, click Manage components.
4. Click Install new, select the file that you downloaded from the Marketplace, and then click Open.
5. Enable this component for your application by selecting the Enabled check box, and then click OK.
6. In the list of enabled components, verify the Jira component and its version, and then save the rule
form by clicking Save.
7. Update the PM_Jira_AuthProfile Authentication Profile instance with credentials that you plan to use to
access your Jira system through REST authentication:
Provide the user ID as user name and the API token for password. If your Jira server does not
support API token, use your Jira password.

For more information about Jira API token, refer to the Atlassian documentation.

To use a method of authentication other than Basic, delete and re-add the PM_Jira_AuthProfile
instance by using the same name for the new version.
8. In the authentication profile, select the Preemptive authentication check box.
9. In the navigation pane of Dev Studio, click your operator icon, and then click Preferences.
10. In the Project management section, in the User ID field, enter your Jira details:
To integrate with Jira version that is GDPR-complaint, enter your Jira account ID.
To integrate with Jira version that is GDPR non-complaint, enter your Jira user ID.
11. Click Save.
12. If your Jira version is GDPR non-compliant, perform additional configurations to integrate:
a. Expand the SysAdmin category, and then click RuleSet.
b. Click the JiraIntegration ruleset, and then open the IsAccountIDSupportedByJIRA rule.
c. Click Save Save as .
For more information about saving rules, see Copying a rule or data instance.
d. On the Advanced tab of the new rule, set the When rule name to Never, and then click Save.
e. Perform check-in.
For more information about checking in rules, see Checking in a rule.
13. In the header of Dev Studio, click the name of the application, and then click Definition.
14. On the Integration & security tab of the Application rule form, in the Agile Workbench
integration section, click Configure integration.
15. Select Jira.
16. Provide the API URL for Jira, and then click Connect.
17. Associate your Agile Workbench work items with a project and release by selecting an existing Jira
project and release, or by creating a project and release.
18. Click Begin integration. Result: All of the user stories and bugs that were created in Agile
Workbench are exported to Jira and associated with the project and release that you specified. A
confirmation message explains the results of the integration process.
19. Click Done.

Documenting your application

Building your first application
Integrating Agile Workbench with Jira in Pega Platform 7.3.x to
7.4.x
Capture real-time feedback about an application development project directly in the application with the
Agile Workbench tool. By using the Atlassian Jira component that is available from Marketplace, you can
continue to use a real-time Agile methodology and integrate Agile Workbench with Jira to take advantage of
its project management features, such as project and issue tracking, Scrum and Kanban support, backlog
prioritization, and sprint planning.

Before you begin: Prepare for the integrating Agile Workbench with Jira:

Disconnect any existing integration to a project management system. On the Integration & security
tab of the Application rule form, in the Agile Workbench integration section, click Configure
integration, and then click Disconnect integration.
Ensure that your Jira version is GDPR non-compliant. For more information, refer to Atlassian
documentation.

1. Download the Jira component from the Marketplace.

2. In the header of Dev Studio, click the name of the application, and then click Definition.
3. On the Definition tab, in the Enabled components section, click Manage components.
4. Click Install new, select the file that you downloaded from the Marketplace, and then click Open.
5. Enable this component for your application by selecting the Enabled check box, and then click OK.
6. In the list of enabled components, verify the Jira component and its version, and then save the rule
form by clicking Save.
7. Update the PM_Jira_AuthProfile Authentication Profile instance and populate it with the user ID and
password that you use to access your Jira system through REST authentication.
If you want to use a method of authentication other than Basic, delete and re-add the
PM_Jira_AuthProfile instance, using the same name for the new version.
8. In the navigation pane of Dev Studio, click your operator icon, and then click Preferences.
9. In the Project management section, in the User ID field, enter your Jira user ID, and then click
Save.
10. In the header of Dev Studio, click the name of the application, and then click Definition.
11. On the Integration & security tab of the Application rule form, in the Agile Workbench
integration section, click Configure integration.
12. Select Jira.
13. Provide the API URL for Jira, and then click Connect.
14. Associate your Agile Workbench work items with a project and release by selecting an existing Jira
project and release, or by creating a project and release.
15. Click Begin integration. Result: All of the user stories and bugs that were created in Agile
Workbench are exported to Jira and associated with the project and release that you specified. A
confirmation message explains the results of the integration process.

Documenting your application

Building your first application

Creating a specification
Defining and creating specifications for an application is an iterative process that requires input from all
stakeholders. If the information about a specification is detailed and up-to-date, the specification is more
useful during the application development process.

You can associate a specification with one or more rules that implement it. For example, a single
specification can correspond to an entire process, a single step in a flow, and an alternate path.

1. Access specifications from one of the following locations in Dev Studio:

From the Dev Studio menu, click Configure Application Profile Specifications .
From the Application Overview landing page, click the Specifications link in the Details
section.

On the Settings tab of a case type that you open from the Case Type Explorer, click
Specifications.

The value displayed next to the Specifications option shows the number of case-wide
specifications that are defined.
 Result: Any specifications that are currently defined for the application or case are listed. You can
filter the list of specifications based on case type and supporting case type, type of rule that the
specification corresponds to, status, complexity, release, and iteration. You can also filter by searching
for keywords in the specification name and description.
2. Click Create specification to open the Add/Edit Specification modal dialog and specify the
following information:
The name of the application
The case type or supporting case type
The Ruleset and Ruleset version
3. On the Details tab of the rule form, specify additional information, such as a short description and
detailed description of the specification, the status and complexity of its implementation, the type of
rule it corresponds to, the target release and iteration, the primary business objective that it supports,
and its business impact.
4. In the Attachment section, add attachments (files and URLs) that provide more information about the
specification.
5. In the Advanced section, specify more information about the specification, including the actors and
subject matter experts involved, requirements associated to the specification, and conditions for the
successful implementation of the specification.
6. On the Implementations tab, view, add, or remove the rules that correspond to, or link to, the
specification.

Estimating application development

Creating a Microjourney for customer success

Documenting your application

Create documentation to engage stakeholders and give guidance to the end users and developers who
interact with your application. You can generate a physical document or provide embedded information,
based on your audience.

Use the following techniques to document your application:

Creating project documents for stakeholders

Create an application overview to educate stakeholders about the features in your application and to
review the development status of your project. To provide most relevant information, customize the
application overview by including only specific chapters.

Exporting a data model into a document

Share information about a data model in your application with stakeholders and developers so that
they can quickly check if the data model includes all relevant information.

Contents of application overview and data model documents

Provide stakeholders with high level information about your application by generating application
overview and data model documentation. Customize the document to include only relevant
information.

Creating project documents for stakeholders

Create project documents to educate stakeholders about the features in your application and to
review the development status of your project.

Creating a guide for end users

Create an application guide to direct users through a set of tasks. By providing instructional
information, you can help users learn about the functionality that your application provides, configure
complex settings, or extend features with limited assistance.

Describing features to end users

You can use a guided tour to showcase application features in real time. By providing information in a
sequence of pop-up windows, you can help users discover functionality that is available on their
current screen.
 Creating guidance for developers

Create internal documentation to provide guidance to the developers who implement or extend your
application.

Project sizing

Project sizing is a technique for estimating the costs, resources, and time lines that you need to
develop an application. By evaluating your project requirements before you begin development, you
can help ensure that you deliver your application on time and within budget.

Creating project documents for stakeholders

Create an application overview to educate stakeholders about the features in your application and to
review the development status of your project. To provide most relevant information, customize the
application overview by including only specific chapters.

1. In the navigation pane of App Studio, click Overview.

2. In the Application documents section, click Export.
3. Optional: To modify the outline, in the Generate overview document window, click Show outline,
and then:
To include a chapter in the outline, select the check box next to the name of the chapter.
To change the order of the items in the outline, move the chapters.
4. Click Generate, and then perform one of the following actions:
To save the document locally, click Download.
To change the content of the document, click Regenerate document, and then perform steps 3
and 4.

Adopting feature-driven development

Exporting a data model into a document

Share information about a data model in your application with stakeholders and developers so that they
can quickly check if the data model includes all relevant information.

For example, if the aim of your application is to investigate various loan requests, you can quickly check the
information that is collected for every case type, such as Mortgage request or Car loan request.

1. In the navigation pane of App Studio, click Overview.

2. Click Actions Export data model .
3. In the Export data model dialog box, select a format for the file.
4. Click Generate.

Adopting feature-driven development

Contents of application overview and data model documents

Provide stakeholders with high level information about your application by generating application overview
and data model documentation. Customize the document to include only relevant information.

You can include the following details in the application overview:

Case types
Case type details
Graphic representation of stages in case types
Case wide optional processes
Case wide optional actions
Stages in case type details
Statuses associated with each stage
Processes associated with each stage
Stage wide optional processes
Stage wide optional actions
Conditions for skipping a stage
Data types
 Systems of records
References between data types and case types
Roles
Number of operators for each role
Web channels available for each role
Pages available for each role for each web channel
Channels and interfaces
Roles that use a specific channel as a default channel
Roles with access to a specific channel
Features that are defined in the application

A data model document contains the following information that you can export to .xml and .pdf files:

All data types and case types with descriptions

References between data type and case types
System of records for each data type
Fields for each data type and case type with the following details:
Label
ID
Type
Field group type, if applicable
List items, if applicable
Is calculated field
Calculation details, if calculated
Description

Creating project documents for stakeholders

Exporting a data model into a document

Creating project documents for stakeholders

Create project documents to educate stakeholders about the features in your application and to review the
development status of your project.

Before you begin:

Ensure that your application uses features instead of specifications. For more information about the legacy
documents that support specifications, see previous versions of the help on Community.

1. Optional: Align the look and feel of your document with your brand.

Changing the style of a project document

Changing the structure of a project document

2. In the header of Dev Studio, click Configure Application Tools Document .

3. In the Select a document type section, choose a document type:
To generate a document that provides high-level information, such as the application description,
case types, data model, and roles, click Application overview.
To generate a document that provides detailed information on application data, click Data
model.
To generate a document that provides traceability from unfinished features to open work items,
and a brief product overview, click Gap analysis.
4. To control which features you document, select a filter option from the Features to include list.
5. To exclude a chapter from the document, clear the check box next to the chapter name.
6. Click Generate document.
7. Click Document generation completed .
8. Click the document name to open the document in Microsoft Word.

Changing the style of a project document

Use HTML styles to align the look and feel of project documents with your brand.

Changing the structure of a project document

Use a template to change align the structure of project documents with your brand.
 Creating a guide for end users
Creating guidance for developers

Changing the style of a project document

Use HTML styles to align the look and feel of project documents with your brand.

Before you begin: Review your document template for custom styles, because these styles override the
HTML styles that you provide. For more information, see Changing the structure of a project document.

1. Use search to find and open the standard @baseclass.pyRTADocStyle HTML rule.
2. Click Save as Specialize by class or ruleset .
3. In the Add to ruleset field, select a ruleset and version in your application.
4. Click Create and open .
5. On the HTML tab, enter your custom styles in the <style> element.
For example, you can change the font, font size, or colors.
6. Click Save.

Changing the structure of a project document

Use a template to change align the structure of project documents with your brand.

1. Use search to find and open the standard pyNextGenDocTemplate file.

2. Click Download file.
3. In Microsoft Word, change the structure of the template.

For example, you can insert a page or add a header for your company logo.

4. Save the pyNextGenDocTemplate.docx file to your local machine.

5. On the File form, click Upload file.
6. Click Choose File, and then navigate to your local file.
7. Click Open.
8. Click Upload file.
9. Click Save.

Creating a guide for end users

Create an application guide to direct users through a set of tasks. By providing instructional information,
you can help users learn about the functionality that your application provides, configure complex settings,
or extend features with limited assistance.

Before you begin: Create a rule in the Application Definition Application Guide rule category. For
more information, see Creating a rule.

You add structure to an application guide by organizing related tasks into chapters. Each task can include
instructional text and a link to supporting information, such as an external document or a landing page.

For example, you can create an application guide for migrating locally stored information to a database
server. In the chapter for configuring your database, you can add tasks for creating tables, views, and
users. In the task for creating users, you can supplement the instructions with a document that lists
database privileges.

1. Adding a chapter to an application guide

To organize related tasks, add a chapter to an application guide.

2. Adding a task to a chapter in an application guide

To provide step-by-step information in an application guide, add a task to a chapter.

3. Adding supporting information to an application guide

Add supporting information to an application guide to direct users to the resources that relate to their
current task.
 4. Adding an application guide to a portal

Add your application guide to one or more portals so that end users can access it.

Creating guidance for developers

Adding a chapter to an application guide

To organize related tasks, add a chapter to an application guide.

Tip: To support translation, use a paragraph to define your chapter description. For more information, see
Creating a paragraph.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, click Add Chapter.
3. In the Chapter name field, enter text that describes the purpose of this chapter.
4. Provide a chapter description.

To reference a paragraph:

1. In the Description list, select Paragraph.

2. In the Paragraph field, press the Down Arrow key, and then select the paragraph that
describes the chapter.

To manually enter a description:

1. In the Description list, select Rich Text.

2. In the rich text editor, enter and format your chapter description.

5. Click Submit.
6. Click Save.

Documenting your application

Adding a task to a chapter in an application guide

To provide step-by-step information in an application guide, add a task to a chapter.

Tip: To support translation, use a paragraph to define your task description. For more information, see
Creating a paragraph.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click Add task.
4. In the Task name field, enter text that describes the outcome of the task.
5. Provide instructions to complete the task in the task description.

To reference a paragraph:

1. In the Description list, select Paragraph.

2. In the Paragraph field, press the Down Arrow key, and then select the paragraph that
describes the task.

To manually enter a description:

1. In the Description list, select Rich Text.

2. In the rich text editor, enter and format your task description.

6. Click Submit.
7. Click Save.

Creating project documents for stakeholders

Adding supporting information to an application guide
Add supporting information to an application guide to direct users to the resources that relate to their
current task.

Use the following techniques to add supporting information to an application guide:

Linking a URL to an application guide

Link a URL to your application guide to integrate a task with an external resource.

Linking a rule or data instance to an application guide

Link a rule or data instance to your application guide give users direct access to internal resources.

Calling a guided tour from an application guide

Call a guided tour from your application guide to make a task more interactive.

Calling a wizard from an application guide

Call a wizard from your application guide to provide well-defined steps for a complex task.

Linking a help topic to an application guide

Link a standard help topic to your application guide to integrate a task with supporting information.

Linking a landing page to an application guide

Link a landing page to your application guide to give users direct access to internal tools.

Linking a custom section to an application guide

In addition to other types of supporting information, such as URLs and help topics, you can link a
section to your application guide to change the presentation or available actions in a task.

Documenting your application

Linking a URL to an application guide

Link a URL to your application guide to integrate a task with an external resource.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Open URL.
5. In the Display text field, enter a label for the link that users click in the task.
6. In the URL field, enter the web address of your supporting information.
7. Click Submit.
8. Click Save.

Documenting your application

Linking a rule or data instance to an application guide

Link a rule or data instance to your application guide give users direct access to internal resources.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Open rule/data.
5. In the Display text field, enter a label for the link that users click in the task.
6. In the Rule Type field, enter the class that defines the type of rule that you are linking.

For example, all data transforms are instances of the Rule-Obj-Model class.
 7. In the Instance Name field, use one of the following methods to select your rule.

Press the Down Arrow key, and then select the fully qualified name of a rule.

Enter the name of a data instance.

8. Click Submit.
9. Click Save.

Creating a guide for end users

Calling a guided tour from an application guide

Call a guided tour from your application guide to make a task more interactive.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Launch tour.
5. In the Display text field, enter a label for the link that users click in the task.
6. In the Action to take field, select Start tour.
7. In the Tour applies to field, press the Down Arrow key, and then select the class to which the guided
tour applies.
8. In the Tour name field, press the Down Arrow key, and then select the name of a guided tour.
9. Optional: Change the look and feel of the tour stops in the guided tour.
a. Select the Override default tour stop container template check box.
b. In the Template name field, press the Down Arrow key and then select the name of a section
that defines the layout and controls for each tour stop.
10. Click Submit.
11. Click Save.

Creating a guide for end users

Calling a wizard from an application guide

Call a wizard from your application guide to provide well-defined steps for a complex task.

Before you begin: Ensure that your wizard, or screen flow, inherits from the PegaAccel- class. For more
information, see Creating a screen flow.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Run wizard.
5. In the Display text field, enter a label for the link that users click in the task.
6. In the Wizard field, press the Down Arrow key, and then select the class of your wizard.
7. Click Submit.
8. Click Save.

Creating a guide for end users

Linking a help topic to an application guide

Link a standard help topic to your application guide to integrate a task with supporting information.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Open help URL.
5. In the Display text field, enter a label for the link that users click in the task.
6. In the Relative path field, enter the file path to the help topic, relative to the base path that you
provide on the System Settings landing page.
7. Click Submit.
8. Click Save.
 Creating a guide for end users

Linking a landing page to an application guide

Link a landing page to your application guide to give users direct access to internal tools.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. Add a link to the task.

Tip: For an example configuration of the following fields, open the Pega-Landing.pyMainMenu
navigation rule by searching for it or by using the Application Explorer.

a. In the Action type list, select Open landing page.

b. In the Display text field, enter a label for the link that users click in the task.
c. In the Action field, select Display.
d. In the Name field, enter a label for the tab that displays the landing page.
e. In the Class field, press the Down Arrow key, and then select a class that defines harnesses.
f. In the Harness Name field, select the harness that the landing page displays.
g. Decide which tab has focus when users open the landing page.
h. Enter the tab name in one of the following fields, based on the tab's position in the landing page
hierarchy:

Level A

Level B

Level C

5. Click Submit.
6. Click Save.

Creating a guide for end users

Adding action sets to a control
Control form - Actions tab
Available UI actions

Linking a custom section to an application guide

In addition to other types of supporting information, such as URLs and help topics, you can link a section to
your application guide to change the presentation or available actions in a task.

1. Open an application guide by searching for it or by using the Application Explorer.

2. On the Definition tab, expand a chapter in the Chapter name column.
3. Click the Gear icon next to a task name.
4. In the Action type list, select Custom section.
5. In the Action value field, press the Down Arrow key, and then select a section in the Embed-Guide-
Task class path that is not in a Pega- ruleset.

Tip: To support users in App Studio, ensure that the first action in your section calls the
pega.desktop.closeAllDocuments API.

6. Click Submit.
7. Click Save.

Creating a guide for end users

Adding action sets to a control
Control form - Actions tab
Available UI actions

Adding an application guide to a portal

Add your application guide to one or more portals so that end users can access it.
Before you begin: Add the pxLaunchAppGuide control to your portal.

1. In the Dev Studio header, click the name of your current application, and then click Definition to open
the Application form.
2. Click the Documentation tab.
3. If there are no guides defined in the Application Guides section, click + Add guide.
4. In the field that is displayed, press the Down Arrow key, and then select the name of your application
guide.
5. In the Available in column, click portals.
6. Click + Add portal.
7. In the field that is displayed, press the Down Arrow key, and then select the name of a portal.
8. Click Submit.
9. On the Application form, click Save.

Creating a guide for end users

Describing features to end users

You can use a guided tour to showcase application features in real time. By providing information in a
sequence of pop-up windows, you can help users discover functionality that is available on their current
screen.

For example, you can create a tour that gives example use cases for the different tools in a web channel.

1. Creating content for a guided tour

You can use sections to create the content for each pop-up window, or tour stop, in a guided tour. By
using a common format, you can associate your content with application features more quickly.

2. Associating content with a feature in a guided tour

You can associate content with a feature to create a tour stop in a guided tour.

3. Integrating a guided tour with your application

You can use one or more controls to integrate a guided tour with your application. By defining the
conditions that start, stop, or restart your tour, you can respond to the actions that users take on the
screen.

Viewing test coverage reports

Documenting your application

Creating content for a guided tour

You can use sections to create the content for each pop-up window, or tour stop, in a guided tour. By using
a common format, you can associate your content with application features more quickly.

1. Create a section that contains the text for the tour stop.

You can add action controls to the section, however, all elements must be read-only. For more
information, see Creating sections.

2. Find a section in a form or portal, that contains the application feature for your tour stop.
Search for the section by name.
In the Application Explorer, navigate to the section by class.
Use Live UI to inspect sections on the screen.
3. On the Section form, click an element, such as a field or layout.
4. If you are in full section editing mode, click the Gear icon.
5. In the Cell properties dialog box, enter a unique string identifier in the Tour ID field.
6. Click Submit.
7. Click Save.

Enabling run-time branching and editing

Documenting your application
Associating content with a feature in a guided tour
You can associate content with a feature to create a tour stop in a guided tour.

1. Find and open a guided tour, by searching for it or by using the Application Explorer.
2. If there are no guided tours available, create one in the User Interface Guided Tour rule category.

For more information, see Creating a rule.

3. On the Definition tab, click + Add tour stop.

4. In the Tour stop anchor list, select a type of identifier, and then enter an ID in the text field that
identifies an application feature.

Tour ID - A unique string that you set on the General tab of the Cell Properties panel on the
Section form.

Custom css selector - A string that you define, which contains a pattern for finding elements on
the screen.

5. In the Title field, enter the text that is displayed above the content for your tour stop.
6. In the Tour stop section field, press the Down Arrow key, and then select the section that defines
your content.
7. In the Show when list, select an option to control when the tour stop is displayed at run time.
8. If your tour stop relies on the presence of a specific element, select a type of identifier, and then enter
an ID for that element in the fields that are displayed.
9. Optional: To change the order of your tour stop, drag it to a different position on the form.
10. Click Save.

Creating project documents for stakeholders

Integrating a guided tour with your application

You can use one or more controls to integrate a guided tour with your application. By defining the
conditions that start, stop, or restart your tour, you can respond to the actions that users take on the
screen.

Before you begin: Ensure that the users in your target audience have write permission for the Data-
Preference-Operator class, because guided tours do not start unless their history can be recorded.

1. Add a control to the section that starts the tour.

a. Find and open a section to start the guided tour, by searching for it or by using the Application
Explorer.
b. On the Design tab of the Section form, add any field, or control, to the section. For more
information, see Creating sections.
c. Click the field to edit it.
d. If you are in full section editing mode, click the Gear icon.
e. In the Cell properties dialog box, click Change, and then click Other in the Custom control
category.
f. In the autocomplete field, enter one of the following controls:

pxGuidedTourAutoStart – Starts the tour one time per user.

pxGuidedTourAutoStartOncePerSession – Starts the tour one time per session, to support

users who share the same log-in credentials.

2. Associate the control with your guided tour.

a. In the Cell properties dialog box, click Parameters.
b. In the TourClass field, press the Down Arrow key, and then select the class of your guided tour.
c. In the TourName field, press the Down Arrow key, and then select the name of your guided tour.
d. Optional: To start the tour every time that the control is displayed, select the
AutoLaunchAlways check box. This option is available for the pxGuidedTourAutoStart control
only.
3. Click Submit.
4. Click Save.
5. Optional: To support restarting the guided tour, add actions to other elements on the screen.
 a. Follow step 1 to open the Cell Properties dialog box for another section or another element in
the same section.
b. Click Actions, and then click Create an action set.
c. Click Add an event, and then click the type of event, such as mouse click, that initiates the
action.
d. Click Add an action All actions Manage guided tour .
e. In the Action to take list, select Start tour.
f. In the Tour applies to field, enter the class of your guided tour.
g. In the Tour name field, enter the name of the guided tour.
h. Optional: To restart the tour from the beginning instead of the last visited tour stop, clear the
Always continue where left off check box.
i. Click Submit.
j. Click Save.

Specify actions for a control

Creating guidance for developers

Create internal documentation to provide guidance to the developers who implement or extend your
application.

Use the following techniques to create internal documentation:

Adding usage information to a rule

Add usage information to a rule to help developers decide whether they can reuse the rule in their
features or applications.

Adding historical information to a rule

Describe the recent changes to a rule in the rule history to help developers trace your implementation
and compare versions more quickly.

Creating a guide for end users

Adding usage information to a rule

Add usage information to a rule to help developers decide whether they can reuse the rule in their features
or applications.

As a best practice, provide usage information when you create a rule.

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

2. Click the History tab.
3. In the Documentation section, enter text in the Description field that describes the purpose of your
rule.
4. In the Usage field, enter text that helps developers understand how to use this rule.

For example, you can describe the expected inputs and outputs.

5. Click Save.

Adding historical information to a rule

Setting rule status and availability
Adding a custom field

Adding historical information to a rule

Describe the recent changes to a rule in the rule history to help developers trace your implementation and
compare versions more quickly.

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

2. On the History tab, click View full history.
3. Click History For All Versions.
4. In the Add Memo field, enter text that describes the differences between this version of the rule and
 the prior version.
5. Click Add Memo.

Viewing rule history

Comparing rule versions

Project sizing
Project sizing is a technique for estimating the costs, resources, and time lines that you need to develop an
application. By evaluating your project requirements before you begin development, you can help ensure
that you deliver your application on time and within budget.

You size a project by entering values in an estimator that has options and formulas that are specific to your
implementation methodology.

You can share sizing information with stakeholders by exporting estimates into the .xlsx file.

Estimating application development

For more accurate project planning and enhanced communication with your stakeholders, create
application development time estimates. When you estimate the duration of your project, you clearly
state how much time and effort your development team needs to deliver an application that reflects
its specific design and required elements.

Sizing an application development project

Estimate the time and effort that you need to build an application to quickly allocate and schedule
resources before you begin development.

Implementation methodologies

Estimating application development

For more accurate project planning and enhanced communication with your stakeholders, create
application development time estimates. When you estimate the duration of your project, you clearly state
how much time and effort your development team needs to deliver an application that reflects its specific
design and required elements.

Before you begin: Define the main elements of your application:

Create a case type, and then define the case life cycle by adding stages, processes, and steps. See
Adding case types to organize work.
Create personas that represent users of your application. See Adding personas to organize users.
Create data objects that visualize the information that your cases require to reach the resolution
stage. See Adding data objects to organize data.
Create features that represent usable functionalities in your application. See Creating features.

A project estimate considers various factors, such as the complexity of the application elements, the
number of available teams to work on developing the application, and having a configured development
environment to build your application. The creation of estimates in Pega Platform is automated. After you
provide the required values, the project estimator calculates the expected development duration. To share
the estimation results with stakeholders outside Pega Platform, you can export the estimates into an .xlsx
file.

1. In the navigation pane of App Studio, click Overview.

2. In the Application profile section, click Manage.
3. In the Application profile workspace, click Estimator.
4. In the Estimator section, in the Release list, select the release for which you want to calculate the
estimate. For example: Create a collective estimate for all defined releases by selecting All.
5. In the Delivery list, select the implementation method that your development team uses. For
example: Select Scrum/Agile.
Non-Agile methodologies increase the estimated effort and duration by 20%.
6. In the Number of teams field, specify how many teams can work on the project.
7. In the Scrum maturity list, select a value that describes the customer's experience with scrum
projects.
 Medium maturity increases the estimated effort and duration by 7.5%, and low maturity by 15%.
8. In the Staffing model list, select a value that indicates the level of cooperation between the customer
and Pega.
In the co-production model, it is assumed that a business architect and two system architects from the
customer side join each development team.
9. In the Environment list, select the environment on which you want to deploy the application.
Creating a new on-premises environment elongates the estimated effort and duration by 10%.
10. In the Organization complexity list, select an option that indicates how many levels and regulations
your organization has.

Organizations with high complexity comply with external regulations and additional validation
requirements, such as government organizations and those in the financial, healthcare, and
pharmaceutical industries.

A high complexity level increases the estimated effort and duration by 20%.
11. In the Data import effort list, select an option that describes the complexity level of the effort
required to migrate data from the legacy system to the new Pega system.
A high complexity level increases the estimated effort and duration by 30%, medium by 20%, and low
by 10%.
12. Click Calculate estimate. Result: The estimator calculates the expected development duration in
hours and weeks, with a division between Pega and customer hours. The estimator also includes
detailed information about the number and complexity of the items in your application, such as case
types, personas, data objects, and features.
13. Optional: To import the estimate to an .xlsx file, in the Application overview workspace header, click
Actions Export estimate as .xlsx file . Result: App Studio automatically saves the .xlsx file to your
machine.

Creating a Microjourney for customer success

Creating a top-level case type
Documenting your application

Sizing an application development project

Estimate the time and effort that you need to build an application to quickly allocate and schedule
resources before you begin development.

Note: To take advantage of low-code solutions that Pega Platform offers, switch to App Studio to estimate
your project in a convenient and low-code way. For more information, see Estimating application
development.

1. In the header of Dev Studio, click Configure Application Tools Sizing .

2. In the Application list, select the name of your application.
3. In the Implementation methodology list, select an option that describes your process for
application development.
Caution: Ensure that the methodology that you select is correct, because the project sizing tool that
you generate is not compatible with other methodology types.
4. Optional: To control which items are included in the project sizing tool, provide filter criteria.

To filter specifications by event:

1. In the Included specifications list, select a type of action.

For example, you can find specifications based on the time that they were created.

2. In the Date field, enter a calendar date that your application evaluates to include
specifications in the project sizing tool.

To filter specifications by category:

1. In the Case types and supporting specification categories section, click Make
selection.

2. Select the check box next to a category name to include specifications with this category
type in the project sizing tool.

3. Click Submit.
 To filter specifications by status:

1. In the Specification status section, click Make selection.

2. Select the check box next to a status name to include specifications with this status type in
the project sizing tool.

3. Click Submit.

To filter case types by name:

1. In the Case types and supporting specification categories section, click Make
selection.

2. Clear the check box next to a case type to exclude it from the project sizing tool.

By default, all case types are selected.

3. Click Submit.

5. Save your settings so that you can reuse your filter criteria in future iterations.
a. Click Save.
b. In the Save Sizing settings dialog box, enter text in the Name field that distinguishes your
settings from other settings for this application.
c. Click Submit.
6. Click Create project sizing , to generate and download a Microsoft Excel file that contains the project
sizing tool.
7. Create estimates for your project.
a. Open the file that contains the project sizing tool.
b. Provide information about your application in relevant cells, by consulting project stakeholders or
the contextual help for each worksheet in the tool.

For example, you can define specifications, identify the type and complexity of each interface, or
override projected hours or productivity rates.

For more information about the formulas and options that you can use, contact your lead
architect or account executive.

c. In the Sizing wizard, click Attach project sizing to application.

d. Click Choose File.
e. Navigate to the directory of the file that contains the project sizing tool, and then click Open.
f. In the Attach Project Sizing dialog box, click Submit.
8. Distribute your estimates to stakeholders for review.

Result:

The timeline from your estimates is included in application profile documents that you generate. You can
generate and attach new estimates to your application as your project matures.

Implementation methodologies

Troubleshooting tools and techniques

Maintain good quality and health of your application by using troubleshooting tools and techniques that
Pega Platform provides. You can view application metrics to locate any issues, and then fix them, so that
you deliver top quality application.

Troubleshooting newly created rules

If there are issues with copying a rule or data instance, see the following information for
troubleshooting help.

Troubleshooting long-lived clipboard pages

Clipboard pages that remain unused for long periods could indicate a design or implementation flaw
that can hurt performance. For example, the application created a page but neglected to use the Page-
Remove method to remove the page after it was no longer needed.
Finding the class of a rule

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

Application debugging using the Tracer tool

You can test and debug your applications by using the Tracer tool. You can test and debug activities,
data transforms, decision rules, service rules, parse rules, and processes. You can select which
rulesets, rules, and events to trace; set breakpoints and watch variables; trace reference properties;
select which requestor session to trace; and add custom events to Tracer output. You can also
troubleshoot offline-enabled applications in a browser by testing scripts that are running when the
application is running.

Clipboard tool

Every connected Pega Platform requestor (including browser-based users, even unauthenticated guest
users) has an associated temporary memory area on the server known as the clipboard. The clipboard
has a hierarchical structure, consisting of nodes known as pages, most of which have a name and an
associated class. Pages act as buffers or temporary copies of object instances (of that class) that are
copied from, or might later be stored into, the Pega Platform database or another database.

Log files tool

In the Log files tool you can view or download the current log files on the server node that you
currently access. Analyzing log files helps you make informed decision when you manage your
applications, as well as identify any issues. As a result, you deliver an application that runs correctly
and avoid exposing your users to errors.

My Alerts display

You can view the current Alert log on the server node produced by your own requestor session by
using the My Alerts display. Select Issues from the Dev Studio developer toolbar.

Viewing and resolving errors

Errors appear if you save a form and the system detects one or more errors.

Viewing in-progress and completed wizards

You can find all wizards that have been started on the All Wizards landing page. You can use this
landing page to clean up incomplete wizards.

Creating connector simulators

With the Connect Simulator functionality, test connect rules in flows and from data pages before the
actual data source is implemented, or when it is not available.

Testing regular expressions

Use the Regular Expression tester to test whether a text pattern matches the regular expression.

The DateTime parse tester tool

Use the Date/Time Parse Tester tool to test whether a text input matches the DateTime patterns used
by Pega Platform, which are based directly on Java standards.

About the bulk Revalidate and Save tool

You can force revalidation in bulk of selected rule or data instances of a single type.

Application Structure landing page

The Application Structure landing page helps you to manage and understand the rulesets, rules,
access groups, and operators that make up your Pega Platform application. Options on this page
display referencing applications, allow you to invite collaborators to the development process, and
provides access to other applications on the system (for operators with permission to do so).
 Designing applications for reuse and extension

Troubleshooting newly created rules

If there are issues with copying a rule or data instance, see the following information for troubleshooting
help.

If your newly created rule is not being executed, it might be related to the rule resolution algorithm
which operates differently on different rule types. See the help topics Completing the Create form for
each rule type to understand specifics of rule resolution for that type.
Many standard rules have Work- as the Apply to key part, but you cannot create additional rules with
Work- as the Apply to key part. When you're copying such a rule, the Save As form defaults the name
of the container class for the current work pool as the Apply to class.
The Save As form is restricted to those users who hold the privilege @baseclass.ToolbarFull or
@baseclass.ToolbarSaveAs.
The availability of your new rule is not specified on the Save As form.
The status of your new rule may be automatically cleared if the following criteria are met:
The original rule status is not internal
One of the following conditions apply
The specified ruleset is not a branch of the original rule
You are changed the Apply To class
The original rule has circumstances defined
You can specialize a rule or create a circumstance of it.

Copying a rule or data instance

Setting rule status and availability

Troubleshooting long-lived clipboard pages

Clipboard pages that remain unused for long periods could indicate a design or implementation flaw that
can hurt performance. For example, the application created a page but neglected to use the Page-Remove
method to remove the page after it was no longer needed.

When building or testing an application, you can discover whether your own processing has created such
"orphan" or "near-orphan" page.

1. Select Clipboard from the developer toolbar in Dev Studio.

2. Once the clipboard is open, select Tools Analyze .
3. In the resulting grid of data, look in the Est Size (KB), Last Passivation, and Last Activation
columns to identify any pages that were automatically passivated but never reactivated.
4. Research whether such pages are needed at all, and whether they can be removed at specific points in
the application, to reduce clipboard size.

Setting passivation and requestor time-outs

Reporting on passivated requestors

Finding the class of a rule

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

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

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

Viewing the XML of a rule

Finding rules by type

Application debugging using the Tracer tool

You can test and debug your applications by using the Tracer tool. You can test and debug activities, data
transforms, decision rules, service rules, parse rules, and processes. You can select which rulesets, rules,
and events to trace; set breakpoints and watch variables; trace reference properties; select which
requestor session to trace; and add custom events to Tracer output. You can also troubleshoot offline-
enabled applications in a browser by testing scripts that are running when the application is running.

You can also trace services and listeners anywhere in the cluster by using RuleWatch trace.

When you set up trace conditions and start tracing, you can view the Tracer output in the Tracer window or
save the Tracer output to your local system.

Note: When using this tool for Customer Service chat interactions, be aware that a single browser session
can be served by multiple requestors.

To troubleshoot offline-enabled applications, enable the use of the Tracer tool in a browser. For more
information, see Troubleshooting offline-enabled applications with the Tracer tool in a browser on Pega
Community.

Note: The Tracer tool is not available during a test coverage session.

For relevant training materials, see the Debugging application errors module on Pega Academy.

Tracer best practices

Use Tracer best practices to make tracing easier and more efficient.

Configuring trace conditions

Before you run the Tracer tool, optionally configure trace conditions, based on the activity, data
transform, rule, and so on, that you are testing and debugging. If you do not configure trace
conditions, the default conditions are used.

Tracing and capturing events

After you have configured the trace conditions, you can begin tracing and capturing events. As you
perform the work that you want to trace, the Tracer displays the traced events according to the
selected trace conditions. Each event is a row in the Tracer window.

Tracing services

You can use the Tracer to monitor any active requestor session. However, a service usually runs in a
new requestor session with a requestor ID that is not created until the service begins processing. At
that point, the processing that the service performs in that requestor session occurs so quickly (in less
than one second), that it can be hard to catch the event to trace it.

Viewing Tracer results in the Tracer window

To maintain the quality of your application, you can use the Tracer window to interact with Tracer
results. Each row in the window represents an event. The Tracer records selected events from the rule
executions, database operations, and other event types that you selected when you configured the
Tracer.

Cluster-wide tracing of service rules

Estimating test coverage

Tracer best practices

Use Tracer best practices to make tracing easier and more efficient.

Trace only one requestor session per operator and node

Do not attempt to start the Tracer when another requestor session on the same Pega Platform node is using
the same Operator ID, or is running the Tracer.

Turn off HTTP compression

Ordinarily, Pega Platform uses HTTP compression to reduce the length of text messages sent to Internet
Explorer. HTTP compression is also used in SOAP messages. This might complicate Tracer debugging
because compression makes it difficult to interpret the messages.

To disable HTTP compression, edit the prconfig.xml file or dynamic system setting and set the value of the
Tracer setting enable-compression setting to "false." This change takes effect the next time your system starts.

Reset this value to enable compression when debugging is complete.

Domain Name System lookups required

In some Pega Platform installations, the ClientHostName value appears only as a numeric Internet Protocol (IP)
address. The true ClientHostName is visible only when the application server is enabled to perform Domain
Name System lookups:

For Tomcat-based systems, set the parameter enableLookups (in the server.xml file) to "true" to allow DNS
lookups.
For Oracle Weblogic, add the parameter ReverseDNSAllowed="true" to the config.xml file to allow DNS lookups.

Duplicate trace error

If the node hosting your trace session fails and you attempt to trace the same service again, you might
encounter a duplicate trace error. Clear stale trace sessions using Admin Studio.

Tracer event queue overflows

Adjusting the buffer size of the Tracer header
Reducing Tracer event output

Duplicate trace error

If the node hosting your trace session fails and you attempt to trace the same service again, you might
encounter a duplicate trace error. Clear stale trace sessions using Admin Studio.

Managing requestors
Tracer event queue overflows
Adjusting the buffer size of the Tracer header
Reducing Tracer event output

Configuring trace conditions

Before you run the Tracer tool, optionally configure trace conditions, based on the activity, data transform,
rule, and so on, that you are testing and debugging. If you do not configure trace conditions, the default
conditions are used.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Optional: Configure Tracer settings. Select which events, event types, rulesets, and pages to trace,
break conditions, and options for the amount of output that you want the Tracer to generate.
3. Optional: Send the Tracer output to a file. This option is useful if you want to work offline with the
Tracer results instead of using the Tracer window.
4. Optional: Set breakpoints to stop the Tracer at specific steps in activities.
5. Optional: Set watch variables to detect when processing has changed the value of a property.
6. Optional: Select a requester session other than your own current session to trace. By default, the
Tracer traces your own requester session.

Configuring Tracer settings

Maintain the quality of your application and quickly locate any issues by tracing selected events with
the Tracer tool. Analyze the Tracer results conveniently by defining what information you want to
include in the output.

Sending Tracer output to a file

You can send the Tracer output to a file if you want to work offline with the Tracer results instead of
 viewing the output interactively in the Tracer window. In addition, you can suppress the event window
to reduce network traffic and workstation load when you only want to view the output offline.

Setting breakpoints in the Tracer tool

You can set breakpoints to pause processing for specific steps in activities. When a breakpoint is set
for an activity, the Tracer window acquires focus when you or the selected requestor connection starts
the activity.

Setting watch variables in the Tracer tool

Set a watch variable to detect when processing has changed the value of a property. Focus returns to
the Tracer window when your work changes the property value.

Selecting a session to trace

By default, the Tracer traces your own requestor session. You can trace another session by using the
Remote Tracer. The Remote Tracer lists every requestor that is connected to your Pega Platform
server.

Tracing and capturing events

Tracer best practices

Configuring Tracer settings

Maintain the quality of your application and quickly locate any issues by tracing selected events with the
Tracer tool. Analyze the Tracer results conveniently by defining what information you want to include in the
output.

For example, you can specify when you want the Tracer to pause processing, or how many events you want
to display in the output.

1. In the footer of Dev Studio, click the Tracer icon.

2. On the Tracer toolbar, click Settings.
3. In the Tracer Settings window, in the Events to trace section, select check boxes of events that
you want to include in the Tracer output:
To trace when an event starts, select the check box in the Start column.
To trace when an even ends, select the check box in the End column.
4. In the Break conditions section, select the conditions under which you want the Tracer to pause
processing:
To pause processing on the first Java exception, select Exception.
To pause processing when a step ends with a Fail status in the pxMethodStatus property value,
select Fail Status.
To pause processing when a step ends with a Warn status in the pxMethodStatus property value,
select Warn Status.
5. In the General options section, select the options that determine the quantity of output in specific
conditions:
To include the Java class details from those properties in the Tracer output, if processing has
properties of mode Java Pages, select Expand Java Pages.

This option might significantly slow processing.

To capture the status of local variables for Begin and End events of activities and their steps,
select Local Variables. Tracer creates an output row each time the system sets the value of a
local variable in an activity.

For local variables with a value of Java null, the Tracer output displays the string null – No Value for
the value of the local variable.

To reduce the performance impact by limiting the amount of clipboard detail for each row in the
Tracer window, select Abbreviate Events.
6. In the Event types to trace section, select event types that you want the Tracer to monitor.
7. Optional: To add additional event types, in the Event Type field, enter the event type, and then click
Add.
8. In the Rulesets to trace section, select the rulesets that you want to trace.
9. Optional: To trace additional pages, in the Pages to trace section, in the Page name field, enter a
 page name, and then click Add.

While the Tracer session runs, the Tracer watches the pages that you add. If the Tracer locates the
pages, links to their content display in the Properties on Page window when you open an event from
the Tracer output.

Note: When you add multiple pages, the Tracer might work slower.

The option to add pages is unavailable if you select Abbreviate Events in the General options
section.

10. In the User interface section, in the Max Trace Events to Display field, enter the number of trace
events to display in the output.
11. Click OK.

Tracer events to trace

You can select the following events to trace in the Tracer Settings dialog box. When selected, the
tracer output includes these events. Events are most relevant for debugging activities rather than
flows or declarative rules.

Tracer event types to trace

You can trace the progress of various events that occur in the system by selecting event types to trace
in the Tracer Settings dialog box. Examples of rules that produce events are flows, declarative rules,
and decision trees rules. You can also trace events related to services and database operations.

Rulesets to trace

You can select the rulesets to trace in the Tracer Settings dialog box. The dialog box lists all of the
rulesets that you can access, in the order they appear in your ruleset list, based on your access group
and other sources.

Reducing Tracer event output

You can reduce the amount of clipboard detail that is sent to the Tracer by using the Abbreviate
Events option. Reducing the amount of output improves the performance of the requestor session that
is being traced so that elapsed time statistics during tracing are closer to the normal values, that is,
the values when processing is not being traced.

Setting the number of lines to display in Tracer

You can change the number of lines that are displayed in the Tracer window to manage network and
workstation load. By default, the Tracer displays the 500 most recent trace lines. You can set a higher
value, which requires additional workstation memory. If you only want to view Tracer output as an XML
file and save it to your local system, set the number of lines to display to zero (0) to reduce the
network and workstation load.

Adjusting the buffer size of the Tracer header

You can adjust the buffer size of the Tracer header to increase the limit for unprocessed events. By
default, the system saves up to 50,000 items for unprocessed events during a Tracer operation. If the
buffer exceeds this limit, Tracer processing ends.

Troubleshooting newly created rules

Tracer events to trace

You can select the following events to trace in the Tracer Settings dialog box. When selected, the tracer
output includes these events. Events are most relevant for debugging activities rather than flows or
declarative rules.

Events to
Description
Trace

Access Deny
 rules to
Events Displays a line at the start of each run of an Access Deny rule.
Description
Trace
Activities Start Displays a line at the start of each activity.

Activities End Displays a line at the completion of each activity.

Activity Steps
Displays a line at the start of every activity step and step iteration.
Start

Activity Steps
Displays a line at the completion of every activity step.
End

Data
Transforms Displays a line at the start of each data transform.
Start

Data
Transforms Displays a line at the completion of each data transform.
End

Data
Transform Displays a line at the start of each data transform action.
Actions Start

Data
Transform Displays a line at the completion of each data transform action.
Actions End

Displays a line for every Java exception. In most cases, processing continues after the
Exception
exception.

For Subscriptions, Tracer displays the following information:

Notification Channel
Subscription Class
Subscription Condition
Subscriber Data
Push
notification For Publish, Tracer displays the following information:

Notification Channel name

Source Page
Published Page
Stack trace of publish

When Rules Displays a line at the start of every when condition evaluation, including preconditions
Start and transitions.

Displays a line at the completion of every when condition evaluation, including

When Rules
preconditions and transitions. If selected, Tracer output shows the results of all when
End
rule executions from all rulesets, regardless of your selected rulesets.

Tracing and capturing events

Configuring Tracer settings
Configuring trace conditions

Tracer event types to trace

You can trace the progress of various events that occur in the system by selecting event types to trace in
the Tracer Settings dialog box. Examples of rules that produce events are flows, declarative rules, and
decision trees rules. You can also trace events related to services and database operations.

For declarative rules, rows of the Tracer output show the operation of the declarative network, that is, the
forward and backward chaining computations that occur automatically.
 Label Description

Enter an additional event type as instructed by Pegasystems Global Customer Services

Event Type
and click Add to enable tracing for this type.

ADP Load Trace the background thread (requestor) that loads a declare page asynchronously.

Adaptive
Trace Adaptive Models.
Model

Alert Include Alert log messages produced by your Thread in the Tracer output.

Asynchronous
Trace asynchronous activity.
Activity

Auto Populate
Trace auto-populated properties.
Properties

Automation Trace automation rules.

CaseType Trace case type rule calculations.

DB Cache Show hits and misses for the rule cache and the conclusion cache.

Show each SQL query sent to the PegaRULES databases and its results, including
DB Query
expansion of the BLOB column.

Show data page activity, including instantiations from properties, calls to data sources,
Data Pages
and responses to those calls.

Declare
Trace collection rules.
Collection

Declare
Trace Constraints rules.
Constraint

Declare
Trace map values (start only).
DecisionMap

Declare
Trace decision tables (start only).
DecisionTable

Declare
Trace decision trees (start only).
DecisionTree

Declare
Trace Declare Expression rules.
Expression

Declare Index Trace Declare Index rules.

Declare
Trace Declare OnChange rules.
OnChange

Declare
Trace Declare Trigger rules.
Trigger

Trace a flow. Rows of the Tracer output identify each flow start and end, each flow shape
Flow
start and end, and the connectors (arrows on the flow diagram).

Interaction Start and end of a user interaction, as defined by the Performance tool.

Linked Page
Trace operations on linked pages that cause retrieval of the target page from a cache.
Hit

Linked Page
Record cache misses for linked properties.
Miss

Locking Trace locking operations. Tracer output shows each lock acquired and each lock released.

Record each run of the Log-Message method that has the SendtoTracer parameter
Log Messages
 Label selected.
Description
Trace Parse XML, Parse Structure, and Parse Delimited rules. Other parse rule types are
Parse Rules not traced.

Predictive
Trace predictive model rules.
Model

Query Trace report queries to identify queries that run against the database instead of
resolution Eleasticsearch.

SOAP Trace detailed SOAP request and response messages for SOAP, SAP, and .NET connectors
Messages and services.

Scorecard Trace scorecard rules.

Services Trace service rules and service activities.

Strategy Trace strategy rules.

Stream Rules Trace all types of stream rules.

Tracing and capturing events

Configuring trace conditions
Configuring Tracer settings
Viewing test coverage reports
Property form: Completing the General tab - Value modes
Log-Message method
Tracing services

Rulesets to trace
You can select the rulesets to trace in the Tracer Settings dialog box. The dialog box lists all of the
rulesets that you can access, in the order they appear in your ruleset list, based on your access group and
other sources.

The Tracer always enforces ruleset access controls. Whether you trace your own session or another user's
session, Tracer output includes only information about the execution of rules in the ruleset that you
selected. The Tracer window does not identify gaps that were caused by this restriction.

The Pega- rulesets listed last are base Pega Platform rulesets. You can select them for tracing, but the
Tracer might produce large quantities of output. You can trace flows in your application rulesets without
selecting the Pega-ProCom ruleset or other base rulesets.

The rulesets that you select do not affect Tracer output for when rules. If you selected the When rules End
option in Events to Trace , Tracer shows the outcome of every rule that you execute, in any ruleset.

Tracing and capturing events

Configuring Tracer settings
Configuring trace conditions

Reducing Tracer event output

You can reduce the amount of clipboard detail that is sent to the Tracer by using the Abbreviate Events
option. Reducing the amount of output improves the performance of the requestor session that is being
traced so that elapsed time statistics during tracing are closer to the normal values, that is, the values
when processing is not being traced.

When you abbreviate events, some watch variables might not operate correctly, and the Pages to Trace
and Local Variables features are disabled. Do not abbreviate events if debugging requires these features.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Settings.
3. In the GENERAL OPTIONS section, select Abbreviate Events.
4. Click OK.
 Setting the number of lines to display in Tracer

Setting the number of lines to display in Tracer

You can change the number of lines that are displayed in the Tracer window to manage network and
workstation load. By default, the Tracer displays the 500 most recent trace lines. You can set a higher
value, which requires additional workstation memory. If you only want to view Tracer output as an XML file
and save it to your local system, set the number of lines to display to zero (0) to reduce the network and
workstation load.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Settings.
3. In the USER INTERFACE section, set Max Trace Events to Display to the number of lines to
display. When Tracer output reaches this limit, the oldest lines are dropped from the window to allow
newer lines to be displayed.
4. Click OK.
5. Restart the Tracer tool for the changes to take effect.

Reducing Tracer event output

Adjusting the buffer size of the Tracer header

You can adjust the buffer size of the Tracer header to increase the limit for unprocessed events. By default,
the system saves up to 50,000 items for unprocessed events during a Tracer operation. If the buffer
exceeds this limit, Tracer processing ends.

1. Edit the prconfig.xml file and add the following lines: <env name="tracer/queue/type" value="file" /><env
name="tracer/queue/file/limit" value=" <env name=" tracer/queue/header/limit" value="nnnnn" /
where nnnnn is a nonnegative integer. Note: As an alternative to updating the prconfig.xml file, you can
use dynamic system settings to configure your application.
2. Stop and restart (or redeploy) the server node to enable the change.

Tracer event queue overflows

Each Tracer session uses a file buffer that holds up to 500 events not yet processed for display. Some
complex tracing situations reach this limit and additional events are discarded.

Reducing Tracer event output

Tracer best practices
Updating dynamic system settings by using Java methods

Tracer event queue overflows

Each Tracer session uses a file buffer that holds up to 500 events not yet processed for display. Some
complex tracing situations reach this limit and additional events are discarded.

The following message is displayed:

Event queue is overflowing on server, events will be discarded.

To avoid this situation, select fewer rulesets or event types, and then repeat the operation.

If this message occurs often, you can increase the file buffer size so that it can contain more events. If the
problem persists after you have set a larger buffer size, your application may contain an infinite loop.

Various conditions can cause the event queue to fill up. For example, if the Tracer and the traced requestor
session are running on one client workstation, then both sessions share the normal limit of two HTTP
operations to the server. If the traced operations involve many HTTP operations, then the Tracer contends
with other browser operations for access to the server. This contention can cause the Tracer to drain the
event queue more slowly, causing an event queue overflow.

Adjusting the buffer size of the Tracer header

Reducing Tracer event output
Tracer best practices
Sending Tracer output to a file
You can send the Tracer output to a file if you want to work offline with the Tracer results instead of viewing
the output interactively in the Tracer window. In addition, you can suppress the event window to reduce
network traffic and workstation load when you only want to view the output offline.

By default, the system saves the output as an .xml file. When tracing in a cluster, and more than one node
reported events for a given RuleWatch, the system saves the output as a .zip file that contains an .xml file
for each node that reported events. If only one node reported events, then the system saves the output as
an .xml file.

For information about viewing the output file and to download a Windows viewer for Tracer output .xml
files, see the Pega Community article Using the Tracer tool to summarize Tracer XML output in Pega 7.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Settings.
3. Optional: To suppress the event window, in the USER INTERFACE section, set Max Trace Events
to Display to 0.
4. Click OK.
5. Perform the work that you want to trace.
6. Click Save. The Tracer output file is saved in the local Downloads folder.

Configuring trace conditions

Tracing and capturing events

Setting breakpoints in the Tracer tool

You can set breakpoints to pause processing for specific steps in activities. When a breakpoint is set for an
activity, the Tracer window acquires focus when you or the selected requestor connection starts the
activity.

Note: You cannot view the clipboard when processing has reached a breakpoint because the requestor
being traced has been paused.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Breakpoints.
3. In the Class Name field, select the Applies To class.
4. In the Activity Name field, select an activity.
5. In the Where to Break field, select one of the following options:
1 to break when the activity starts
the step before which you want to pause processing
all steps to break for each step
6. Click Set Break.
7. Optional: To remove a breakpoint, select the check box in the Remove column and click Remove.
8. Optional: Repeat steps 3 through 6 to add more breakpoints.
9. Click Close.

Configuring trace conditions

Tracing and capturing events

Setting watch variables in the Tracer tool

Set a watch variable to detect when processing has changed the value of a property. Focus returns to the
Tracer window when your work changes the property value.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Watch.
3. In the Page Name field, enter the name of the page or enter param for the parameter page.
4. Either enter the property name without a period in front of it in the Property Name field or select Or
Page Messages to watch this page for page messages.
5. Click Set Watch.
 6. Optional: To remove a watch variable, select the check box in the Remove column and click
Remove.
7. Optional: Repeat steps 3 through 5 to add more watch variables.
8. Click Close.

Configuring trace conditions

Tracing and capturing events

Selecting a session to trace

By default, the Tracer traces your own requestor session. You can trace another session by using the
Remote Tracer. The Remote Tracer lists every requestor that is connected to your Pega Platform server.

The first letter of the session ID identifies the requestor type:

H – Internet Explorer-based users

B – Background users such as agents, service requestors other than for Service Portal rules, and
daemons
A – External applications
P – Access through Service Portlet rules

You cannot trace listener processing because listeners operate as Java threads, not full requestor sessions.
Use remote logging to debug listeners.

1. On the developer toolbar, click Tracer, or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Remote Tracer.
3. Select the session that you want to trace.
4. Click Okay.

Configuring trace conditions

Tracing and capturing events

Tracing and capturing events

After you have configured the trace conditions, you can begin tracing and capturing events. As you perform
the work that you want to trace, the Tracer displays the traced events according to the selected trace
conditions. Each event is a row in the Tracer window.

1. On the developer toolbar, click Tracer or click Actions Trace on an activity, data transform, or
service rule form.
2. Click Play to start tracing.
3. Move or minimize the Tracer window so that you can see the Dev Studio to perform the work that you
want to trace.
4. Perform the work that you want to trace, or when tracing a requestor session other than your own,
wait for the system to perform the work in that session.
5. If you have set a breakpoint for an activity, and the activity starts, the Tracer window acquires focus.
Click Continue to resume tracing. Tracing automatically resumes after one hour.
6. Optional: To remove a breakpoint:
a. Click Breakpoints.
b. Select the Remove checkbox.
c. Click Remove.
7. If the value of a watch variable changes, the Tracer window acquires focus and the Property Inspector
is displayed in the lower left of the window. To view the full Property Inspector display, place your
pointer at the line until a yellow arrow appears and drag the dispaly up. The following fields are
displayed:

Reference – Specifies the page and property being watched.

Old Value – If you clicked Continue and the Tracer finds that the value has changed, the previous
value is displayed.

Current Value – Displays the current value of the property.

8. Click Continue to resume tracing. Tracing automatically resumes after one hour.
 9. To end the watch:
a. Click Watch.
b. Select the Remove check box.
c. Click Remove.
10. Click Pause to stop tracing.

Configuring trace conditions

Tracer best practices

Tracing services
You can use the Tracer to monitor any active requestor session. However, a service usually runs in a new
requestor session with a requestor ID that is not created until the service begins processing. At that point,
the processing that the service performs in that requestor session occurs so quickly (in less than one
second), that it can be hard to catch the event to trace it.

In this situation, it is recommended that you use the Trace Open Rule feature to trace the service rule. You
can use this feature to trace a service request that is invoked from an external client application.

The ability to trace services comes with a performance impact even when you are not actively tracing,
therefore it is recommended that you disable service tracing in production environments and during
performance testing unless you are troubleshooting a related issue.

Service rule tracing is only enabled in environments where the

trace/cluster/ServiceRuleWatchMaxProductionLevel Dynamic System Settings is greater than or equal to
the production level. By default, trace/cluster/ServiceRuleWatchMaxProductionLevel is set to 4, which
means that the ability to trace service rules would not work in a production level 5 environment until
trace/cluster/ServiceRuleWatchMaxProductionLevel is increased to 5.

Owning Ruleset: Pega-RulesEngine

Setting Purpose: trace/cluster/ServiceRuleWatchMaxProductionLevel
Value: <greater than or equal to the production level, for example, 5>

To use the Trace Open Rule feature to trace and debug a service rule:

1. Open the service rule by performing one of the following tasks:

In the developer toolbar of Dev Studio, click Tracer.
In the developer toolbar of App Studio, click Tracer.
2. Click Actions Trace . The Tracer tool window opens.
3. Click Settings to open the Tracer Settings window.
4. In the Event Types to Trace section, select Services.
5. In the Rulesets to Trace section, select the rulesets that contain the service rule and service activity.
6. Click OK to close the Tracer Settings window.
7. Run the rule.
8. Watch the Tracer window as the rule runs. The window includes lines for the start and end of each
service rule execution, lines for the start and end of request mapping, lines for the start and end of
response mapping, and (if these options are selected in the Tracer Settings panel) lines for the start
and end of parse rules, XML Stream rules, and HTML rules.

Result:

The Tracer offers the following trace options for services:

Services – The Tracer adds steps for when the service invocation begins and ends. Nested within those
steps are entries that show when the inbound data mapping begins and ends, and when the outbound
data mapping begins and ends.
Parse Rules – The Tracer adds steps when a parse rule (delimited, structured, or XML) begins and
ends processing.
Stream Rules – The Tracer adds steps when an HTML rule or XML Stream rule begins and ends
processing.

Cluster-wide tracing of service rules

You can trace service rules across a cluster. Cluster-wide tracing makes it easier for you to
troubleshoot services in clustered configurations where a load balancer dynamically assigns service
 requests to nodes in the cluster. This functionality is especially useful for debugging mobile
applications, RESTful Web Services, and other stateless service executions.

Configuring trace conditions

Cluster-wide tracing of service rules

Cluster-wide tracing of service rules

You can trace service rules across a cluster. Cluster-wide tracing makes it easier for you to troubleshoot
services in clustered configurations where a load balancer dynamically assigns service requests to nodes in
the cluster. This functionality is especially useful for debugging mobile applications, RESTful Web Services,
and other stateless service executions.

When tracing across the cluster, the trace feature only captures one trace at a time, which might result in
some concurrent service executions not being traced. All other concurrent service executions in the cluster
continue unimpeded. When the trace in progress completes, the next new service execution in the cluster
is traced. For example, you might see traces for invocation one on node A, invocation two on node C, and
invocation four on node B. This selective tracing approach ensures that tracing with a breakpoint will not
stop all service executions across the cluster.

You can selectively disable cluster-wide tracing based on production level to eliminate performance impact
in production by using the trace/cluster/ServiceRuleWatchMaxProductionLevel dynamic system setting. Set the value to
the maximum production level for which you want to allow RuleWatch tracing for Rule-Service- data
instances. The Trace option will not be shown in the Actions menu for the rule form on systems with a
production level higher than the dynamic system setting's value.

Note: Only one user can trace a service rule at any given time. If a user is tracing a service rule on one
node and another user tries to trace the same service rule on either the same node or a different node, an
error message is displayed.

Viewing Tracer results in the Tracer window

To maintain the quality of your application, you can use the Tracer window to interact with Tracer results.
Each row in the window represents an event. The Tracer records selected events from the rule executions,
database operations, and other event types that you selected when you configured the Tracer.

1. In the footer of Dev Studio, click the Tracer icon.

2. In the Tracer window, analyze the Tracer output:
To learn more about the event and view a Java stack trace if an exception occurred, click the
value in the Line, Rule#, or Step column.
To view the properties that were on the step page when the step began, click the value in the
Step Page column.
To open the corresponding rule, click the value in the Name column.
To view the contents of the parameter page, click the value in the Line column, and then click
Parameter Page Name.
To view the contents of the primary page, click the value in the Line column, click Primary Page
Name.

Tracer results window

The header row of the tracer results window contains the Pega node hash and computer name. For
cluster-wide tracing of service rules, the tracer displays a separate section for each node that reported
events.

Troubleshooting newly created rules

Tracer results window

The header row of the tracer results window contains the Pega node hash and computer name. For cluster-
wide tracing of service rules, the tracer displays a separate section for each node that reported events.

The tracer records selected events from the rule executions, database operations, and other event types
that you selected when you configured the Tracer. Each row represents an event and is color-coded.
 Gray – Activity processing
Orange – Events from flow, decision, or declarative rules
Light blue – PegaRULES database and cache operations

The window contains the following columns. The values of some columns change depending on the type of
traced event.

Column Description

Line Number of events traced, starting at 1 for the oldest.

Thread The Thread object for the step.

The interaction number for the step. This total starts being counted at login and is reset upon
Int
logout.

Count of distinct activities traced. The count is not reset to zero if you clear all the events.
When a single activity is run again later, the previously assigned number is repeated.
Rule#
Rules other than activities are not assigned a number.

For an activity, the method in this step.

For a declarative rule or decision rule, indicates the start or end of a computation.

Step For a when condition rule or Boolean expression, identifies the rule name or (a portion of) the
Method expression.

When you trace a database operation , this column lists the specific operation performed on the
database. (commit, insert, update)

Name of the step page, or =unnamed= if the Step Page column of this step is blank. Step pages
that have messages set on them, such as error messages, have a bright orange background.
Step
Page When you trace a database operation , this column lists the database table affected by the
database operation in the Step Method column.

Step number of this step. If two or more rows appear with the same step number, an iteration is
Step
in process at that step.

Status of the method in the step, from the pxMethodStatus property, such as Good, Fail, or Warn. A
red background marks Fail steps (that are not addressed by a transition).

Exit Iteration marks the end of an iteration step.

In this context, a red Fail row indicates an unhandled exception condition. If a method returns a
Fail status but the step contains a transition, the Tracer row displays the status as Good and has
Status
a normal gray background. This behavior is consistent with the processing status that is to be
perceived by the next activity step to run; it reflects that any error condition that existed has
been noted by the activity.

When you trace a database operation , this column lists the number of bytes involved in a write
to the database.

Watch Properties for which you have set up a watch variable.

Type of event or rule: Step Begin , Step End , Activity End, Constraint, Expression, DecisionTree, MapValue, and so on.
Event
When Begin and When End events identify the start of a when condition rule or similar test, such as
Type
in a precondition or transition.

For Step End and Activity End rows, elapsed time in seconds for the step. The time interval might be
Elapsed
degraded by Tracer operation.

Full name of the rule being traced, showing all key parts.
 Name
Column When you trace a database or cache operation , the Name and RuleSet columns are combined.
Description
The text in this combined column provides details on the rules being searched for in the cache,
or on the size of the database operation.

Ruleset Ruleset and version containing the rule being traced.

Viewing Tracer results in the Tracer window

Clipboard tool
Every connected Pega Platform requestor (including browser-based users, even unauthenticated guest
users) has an associated temporary memory area on the server known as the clipboard. The clipboard has a
hierarchical structure, consisting of nodes known as pages, most of which have a name and an associated
class. Pages act as buffers or temporary copies of object instances (of that class) that are copied from, or
might later be stored into, the Pega Platform database or another database.

Use the Clipboard tool when developing and debugging to:

Examine property values and messages associated with them

Find the information necessary to reference a property — the page and property names
Quickly update, add, or delete page properties
Quickly start activities
Search for properties or property values in all or selected pages

Note: When using this tool for Customer Service chat interactions, be aware that a single browser session
can be served by multiple requestors.

Access the Clipboard tool by clicking Clipboard in the Dev Studio developer toolbar. As you interact with
the Clipboard tool at your workstation, you see a static snapshot copy of your clipboard, which resides in
memory on the server.

Required privileges
The Clipboard tool is available only to users who have access to the @baseclass.clipboardViewer privilege.
Action menu items that update the clipboard contents are available only to users who hold the
@baseclass.clipboardViewerUpdate privilege.

The standard access role PegaRULES:SysAdm4 provides these privileges.

Clipboard tool for debugging

Several methods manipulate the clipboard. As you execute activities that affect your clipboard, you can
examine the results with the Clipboard tool.

For example, when you execute an activity that contains a Page-New method, you can see the resulting
named top-level page in the User Pages section. If you execute an activity that uses the Property-Set
method (on a named clipboard page), you can see the new values.

Mobile Clipboard
Pega Mobile offers a clipboard view similar to the clipboard that you use on your Apple Safari desktop
emulator in Dev Studio. Useful for trouble-shooting and debugging your mobile app, the clipboard is
grouped by User, Declare, Linked Property, and System pages.

The Mobile Clipboard is available only to users who have access to the @baseclass.clipboardViewer
privilege. The access roles PegaRULES:SysAdm4 and PegaRULES:ProArch4 provide these privileges.

In the Safari desktop emulator, access the clipboard by using a tap and hold gesture on the mobile app.
Display the clipboard for the main content panel and modal/overlay windows. Tap and hold does not display
the clipboard for the main navigation panel, the toolbar menu, or a menu bar in a section. You can also add
the clipboard as a navigation menu item.

See the Pega Community article Mobile Clipboard.

 Using the Clipboard tool

The Clipboard tool displays two panels.

Setting property values with the Clipboard tool

Maintain the best quality of your application by testing it with the Clipboard tool. To test or debug your
application, set values for the properties that your application logic uses, and then check whether the
application logic behaves as expected.

Adding a user page to the clipboard

Quickly exercise your application logic in different scenarios by manually adding user pages in the
Clipboard tool to mock the state of the application. For testing purposes, you can add user pages
manually when your application is still in development. As a result, development efforts can continue
in parallel rather than in sequence, which helps you deliver working software more rapidly.

Measuring clipboard size

The clipboard display shows the contents of the clipboard, but not its size in bytes. Large clipboards
can affect performance because memory in the Java Virtual Machine (JVM) supporting the Pega
Platform holds the clipboards of all requestors.

Indirect pages

An indirect page is a page that the system finds by searching the clipboard at run time. The page
reference to an indirect page starts with the keyword prompt followed by the page name.

Application debugging using the Tracer tool

Using the Clipboard tool

The Clipboard tool displays two panels.

The left panel displays, for a selected thread, the page structures in a hierarchical tree format. As you
interact with Dev Studio, you create new Threads in a variety of ways. These include starting user
portals, opening rules or landing pages in portal tabs, or creating work items in a process or a wizard.
The right panel contains the names and values of Single Value, Value List, and Value Group properties
and messages for one page selected in the left panel.

To interact with the clipboard:

1. Select a Thread from the Clipboard header. Every Thread in your requestor session has a clipboard
context. Each open tab on Dev Studio has a dedicated Thread. Thread names correspond to their tab
names; work item Threads are identified by their IDs. By default, the thread for the selected tab
appears when you open the clipboard.
2. Select an aggregate object in the left panel, which may be of mode Page, Page List, Page Group, Value
List, or Value Group.
3. Review or interact using menus and links in either panel.

Review page structure in the left panel

The left panel presents the entire clipboard for the currently selected Thread as a tree, growing from the
left.

Click a name or expand arrow to display any node in the left panel to view the page structure it contains.
Click again or click a collapse arrow to hide) the pages within a page.

The clipboard contains three groups of pages:

User Pages – Top-level pages created by your normal processing, sorted alphabetically by page name.
For more information on adding user pages to facilitate testing, see Adding a user page to the
clipboard.
Data Pages – Read-only data pages (created if necessary when accessed, defined by data pages rules).
Linked Property Pages – Read-only pages retrieved because a harness, section, flow action or other rule
 contained a property reference based on a linked property. These pages are read-only, and never
updated. They are removed automatically whenever your requestor performs any Commit operation.
System Pages – Top-level created pages created during authentication. These correspond to the
organization, division, access group, application rule, and organization unit of the operator. None of
the pages are available to guest users.

Three single, system-maintained pages are always present and are displayed when you click the Show
Advanced link at the bottom of the tree:

pxThread – Known as the thread page, it provides the context of clipboard.

pxRequestor – Known as the requestor page, it contains information about your access roles, RuleSet
list, and HTTP protocol parameters.
pxProcess – Known as the process page, it contains information about the server's Java Virtual
Machine and operating system.

Each top-level page may contain other pages that in turn may contain other pages, and so on. For most
pages, the class of the page appears in parentheses after the page name and a single space. (For group
and list properties, additional parentheses appear around subscripts.)

Every embedded page is defined by a property. Properties of mode Page , Page Group , and Page List may
appear as embedded on the clipboard. Pages may contain properties (of any mode) and messages.

The branch structure of the tree in the left panel directly corresponds to the fully qualified name of a
property reference. For example, the property reference:

pyWorkPage.pxFlow(VacationRequest).pyConfirmationNote

identifies a Single Value property named pyConfirmationNote embedded on a page named pxFlow("VacationRequest"),
an element of a Page Group named pxFlow on the top-level user page named pyWorkPage.

Square brackets and the term [Refers to ..] indicate a reference property. The text in the square brackets
identifies the non-reference page.

Using the Tools menu

Click the Tools menu on the Clipboard header to do the following:

Select Analyze to review a tabular report showing the approximate size in kilobytes of each clipboard
page, the page name and class, the number of accesses (read or update), and date and time of the
last access, and passivation history. See Understanding passivation and requestor timeouts. If the
Collect Details mode is enabled, the display contains stack traces showing how pages were created or
deleted and historical information about pages no longer on the clipboard.

Select Collect Details to enable, or disable, automatic collection of detailed clipboard size and access
information. A check mark next to this menu option indicates that data collection is active. A pop-up
window confirms your menu action. While enabled, select the Analyze Clipboard option to review the
size and use of each page on the clipboard, including pages that were removed during the data
collection period.

Note: To eliminate unnecessary processing, disable this facility except when you need the additional detail
it provides.

Using right-click command menu

You can perform the following right-click commands on a page you select in the tree. Options that update
the clipboard are available only to users who have the hold the clipboardViewerUpdate privilege.

Command Description

Refresh Select to cause the Clipboard tool to access and redisplay only a single aggregate property
Page and its elements.

Delete Select to delete a page. Confirm the deletion in the resulting dialog box.Note: You cannot
Page delete a data page.
 Command Select to display the page's underlying XML. Use this command to see pz properties and other
Description
Show XML clipboard entries that aren't truly properties.

Show
Select to display the page's underlying JSON, which is sent to the mobile client.
JSON
Select to test a rule without the need to create a test activity that creates the pages and
properties expected as starting conditions for the rule. The selected page becomes the
primary page for the activity.

Execute An Execute Activity dialog appears and displays the class of the selected page in the Page
Activity Class field.

1. Enter the Activity Name key part.

2. Click Get Params to enter parameter values.
3. Click Execute Activity to run it.

Review property values in the right panel

When you select a page in the left panel, all Value List, Value Group, and Single Value properties on that page
appear in the right panel, sorted by property name. Property messages appear in red text.

Click a property name to open its form in Dev Studio.

Values of TextEncrypted properties are encrypted. They appear as blank in this display.

The following options are available in the right panel.

Option Description

Refresh Click to cause the Clipboard tool to access and redisplay the properties on the current page.

Select to add a single value property to a page, modify an editable property value, or delete an
editable property from the page. When you select Edit the following occurs:

Editable property values appear in text boxes

The Add option appears above the properties list
Edit The Delete icon appears at the end of a row containing an editable property

When you are finished with your edits, click Save to keep your updates and save the page to
the memory, or click Cancel to cancel them.

Note: You cannot edit a read-only data page outside of the data page load and post-activity
process.

To add a single value property to a page, select the Edit option, select a row in the list, and
Add click Add. Enter the property name and value in the Add properties dialog box.Note: You
cannot add an embedded property.

This option is available when you click Edit. Click Save to save your updated page to the
Save memory.Caution: Pega Platform does not validate properties on the page. This action can
introduce invalid data into the memory.

This option is available when you click Edit. Select a row containing an editable property and
Delete
click to delete it from the page.

Discard This option is available when you click Edit. Click Discard to cancel your updates.

Click to select the Show XML, Show JSON, or Execute Activity commands as described
Actions
previously.
Caution: Changing your clipboard contents or structure may affect the integrity of your system or your
application results. Change clipboard values with this tool only in a debugging situation. Deleting properties
or saving altered pages may introduce invalid data into the memory.
Page and property messages
Clipboard page names with errors appear in red text on the left panel. Click the name to view messages
associated with properties on this page in the right panel.

A page message is a text clipboard value that is generated by the system and associated with a page.
Similarly, a property message is a text clipboard value that is generated by the system and associated with
a property. These messages can convey error conditions, progress, or exceptions to a user.

Although messages appear as values on the clipboard, they are not defined through properties. Generally, a
clipboard page containing messages cannot be saved, because typically, the message indicates that the
page, or a property on it, is invalid. The value of a property might not meet the requirements of a
permanent instance of the page's class because of missing or incorrect data.

Property messages are associated with a single property and value. They might indicate that the property
value is not valid. Page messages are associated with an entire page.

When a workstation user submits an HTML form, previous page messages corresponding to the input are
cleared, and property messages are cleared for any value that changed.

Properties and pages not found on the clipboard

The following items are not visible on the clipboard:

Properties with Internal status ( properties with names that start with pz ). These standard properties
support internal Pega Platform operations. To view these properties you can override the
@baseclass.pyShowInternalProperty when rule or right-click in the left panel and select Show XML.
Primary pages of some activities. The parameter page of an activity. Use the Tracer to view these
pages.
Properties of mode Java Object, Java Object Group , and Java Object List .

Note: The Application page contains much, but not all, of the properties that make up the requestor's
application rule.

Clipboard tool
Adding a user page to the clipboard
Page names and reserved pages

Setting property values with the Clipboard tool

Maintain the best quality of your application by testing it with the Clipboard tool. To test or debug your
application, set values for the properties that your application logic uses, and then check whether the
application logic behaves as expected.

For example, to test the logic of a child case type, before you finish creating its parent case type, you can
provide a sample of the data that the child case type normally inherits from its parent.

For relevant training materials, see the Clipboard data module on Pega Academy.

1. In App Studio, navigate to an element that you want to test. For example: To test a child case, in the
navigation pane of App Studio, click Case types, click a case type that you want to open, and then
click Save and run .
2. In the footer of App Studio, click Toggle runtime toolbar Clipboard . Result: The Clipboard
Viewer window opens. The navigation pane lists pages in the memory that are associated with the
thread that you select in the Thread list.
3. In the navigation pane, click the page that stores the values that you want to edit.
4. In the Clipboard page section, click Edit.
5. In the Value column, provide a value for the property that you want to test or debug. For example:
Set the value of a property to false, as shown in the following figure:

Editing property values in the Clipboard tool

 6. Click Save.
7. Populate the process that you want to test or debug with the new clipboard data. For example: Bring
the case to a resolution.
8. Verify that the field values match the test values.

Clipboard tool
Using the Clipboard tool

Adding a user page to the clipboard

Quickly exercise your application logic in different scenarios by manually adding user pages in the
Clipboard tool to mock the state of the application. For testing purposes, you can add user pages manually
when your application is still in development. As a result, development efforts can continue in parallel
rather than in sequence, which helps you deliver working software more rapidly.

For example, in an insurance claim case, you want to test a process that includes a Load data page step,
but the case currently lacks a data model. In this situation, you can use the Clipboard tool to create mock
pages to verify that the process runs correctly against a proposed model.
You add a user page during application development in the following situations:

To avoid building logic into your application that provides mock values for application validation.
To manually test your application against a data structure that is not available yet.

For relevant training materials, see the Clipboard data module on Pega Academy.

1. In App Studio, navigate to an element that you want to test. For example: To test a case, in the
navigation pane of App Studio, click Case types, click a case type that you want to open, and then
click Save and run .
2. In the footer of App Studio, click Toggle runtime toolbar Clipboard . Result: The Pega Clipboard
window opens. The navigation pane lists pages in memory that are associated with the selected
thread.
3. In the Thread list, select the thread in which you want to add a user page.
4. In the navigation pane, right-click User Pages, and then click Add Page.
5. In the Add New Page dialog box, in the Page Name field, enter a name for the new page.
6. Optional: To create a list of properties based on a specific class, in the Page Class field, enter or
select the class to which the user page belongs.
Otherwise, the page that you create is classless.
 7. Optional: To provide values in the user page by using a data transform, in the Data Transform field,
specify the data transform that supplies the initial values for the user page. For example: Set the
value of a field to the name of a product, as shown in the following figure:

Adding a user page with a data transform

8. If the data transform sends parameter values to the user page, click Get Params, and then enter the
parameter values that you want to set in the appropriate fields.
9. Click Submit.

What to do next: Manually set the values for particular properties. For more information, see Setting
property values with the Clipboard tool.

Clipboard tool
Using the Clipboard tool
Viewing test coverage reports

Measuring clipboard size

The clipboard display shows the contents of the clipboard, but not its size in bytes. Large clipboards can
affect performance because memory in the Java Virtual Machine (JVM) supporting the Pega Platform holds
the clipboards of all requestors.
You can use the Performance tool to see the size of your clipboard in bytes, or to track the growth and
contraction of your clipboard over time.

1. In the developer toolbar, select Performance.

2. Click Add reading with Clipboard Size.

Use Admin Studio to determine the size of each requestor's clipboards and the size of each page. For more
information, see Managing requestors and the Admin Studio help.

1. Click Admin Studio Resources Requestors .

2. In the options menu, click Analyze clipboard.

Clipboard tool
Using the Clipboard tool

Indirect pages
An indirect page is a page that the system finds by searching the clipboard at run time. The page reference
to an indirect page starts with the keyword prompt followed by the page name.

Note: This type of page is deprecated but still supported for rules that used this feature prior to Pega 7.1.

With a Call or Branch instruction, the calling activity can identify parameters to the target activity by using
indirect page references. For example, if you identify a page as promptALPHA, the system searches the
clipboard for pages named ALPHA.

You cannot use symbolic page names (such as primary or param ) after the keyword prompt; an explicit page
name is required.

You can use indirect pages in these rule types:

Activities
Correspondence
Harness
HTML
JSP
Paragraph
Parse Infer
Parse Structured
XML

On the Pages & Classes tab of these forms, indicate that a page referenced in the rule is an indirect page
by setting the Mode field to prompt.

Page names and reserved pages

Log files tool

In the Log files tool you can view or download the current log files on the server node that you currently
access. Analyzing log files helps you make informed decision when you manage your applications, as well
as identify any issues. As a result, you deliver an application that runs correctly and avoid exposing your
users to errors.

The available log files depend on the contents of the prlog4j2.xml file for the current node. The log files can
include:

PEGA
A text file that contains warnings, errors, and information messages about internal operations.

ALERT
Performance-related alerts that are triggered by prconfig settings, or implicit, default values. A text file
with fields separated by a single asterisk character.
ALERTSECURITY
Alerts identified by the prefix SECU that suggest incorrect configuration of the Internet Application
Composer facilities, or overt attempts to bypass system security features through URL tampering. For
 more information, see Performance alerts, security alerts, and AES on Pega Community.
BIX
Files that were created during an extract of operation rules by the optional Business Intelligence
Exchange product.
CLUSTER
A file that includes information about the setup and run-time behavior of the cluster, and other
information provided by the clustering technology.
DATAFLOW
A file that includes data flow events in the system, such as a number of running threads, a number of
newly created threads, or a number of stopped threads.
MOBILE
A text file that includes information about running of your mobile application. You can retrieve logs for
a user that you select and specify how much information you want to include in the file. For example,
the file can include information about failures during logging to a mobile application in an offline
mode.

Failures of data synchronization of your mobile application are part of the PEGA0066 alert. For more
information, see PEGA0066 alert: Mobile App Data-Sync Failure on Pega Community.

PegaRULES-SecurityEvent
A file that contains information about security-related events that occur in the system, such as login
failure or a password change. When security-related events occur in unusually large numbers or in
suspicious patterns, they might represent a security issue.

Viewing logs

Analyze information about your system by viewing log files. Log files gather data about internal
operations, system performance, or security so that you can make informed decisions when you
manage your applications.

Downloading log files

To view your log files later or to share the logs with other team members, download the log files. As a
result, you can analyze system performance at a time that is convenient for you.

Viewing log files in an external log viewer

You can view log files using an external log viewer, such as Kibana. An external log viewer can help
you visualize logs and monitor potential issues.

Log levels for log categories

You can select which log messages your log files include by creating log categories and associating log
levels with your categories.

Creating log categories

Structure log messages into categories by creating custom log categories. Grouping loggers into
categories makes it easier to manage log levels of loggers, because you do not have to remember the
names of individual loggers.

Logging Level Settings tool

You can use the Logging Level Settings tool to temporarily override the severity settings in the
prlog4j2.xml file for the current node and control which logging events are displayed in the Pega log.
For example, you can change the logging level for activities in the Work- class from FATAL to DEBUG
for troubleshooting purposes.

Renaming Pega logs

If two or more Pega Platform servers are installed in a single application server instance, they write
lines to a common Pega log file. To prevent this from occurring, you can change the name or path of
the Pega log for a node by modifying the prlog4j2.xml file.

Rolling a log file

You can update the prlog4j2.xml file or dynamic system setting to cause a new log file to be created at
 the start of each day or on a periodic basis, rather than only at startup. This is known as "rolling" the
log file.

Displaying node type in the log

You can optionally choose to display the system node type in the Pega Platform log.

Viewing and resolving errors

Application debugging using the Tracer tool

Viewing logs
Analyze information about your system by viewing log files. Log files gather data about internal operations,
system performance, or security so that you can make informed decisions when you manage your
applications.

The log files match the current operator ID for all the sessions on the server node.

1. In the header of Dev Studio, click Configure System Operations Logs .

2. On the Logs tab, in the Log utilities section, click Log files.
3. In the Log File Download window, click a file name to view one of the logs.
The initial display shows log file entries for your operator ID, 25 lines at a time.
4. Optional: To adjust the display to your needs, change or remove the log filters:
To change the number of lines, in the Lines Per Page field, enter a new value, and then click
Apply.
To change the number of pages that the window displays, in the Number of Pages Presented,
enter a new value, and then click Apply.
To filter the logs by a user, in the Filter by field, enter an operator ID, and then click Apply.

If you clear the Filter by field, the results include logs for all users in the system.

5. After you analyze the logs, return to the list of logs by clicking Back.

Log files tool

Downloading log files
Viewing log files in an external log viewer
My Alerts display

Downloading log files

To view your log files later or to share the logs with other team members, download the log files. As a
result, you can analyze system performance at a time that is convenient for you.

1. In the header of Dev Studio, click Configure System Operations Logs .

2. On the Logs tab, in the Log utilities section, click Log files.
3. In the Log File Download window, in the Download column, select the type of file that you want to
save on your machine:
To download a log as a text file, with .txt as the file type, click text.
To download a log as a .zip file, click zip.
4. In the Sign in dialog box, enter the authentication information for your application server, and then
click Sign in.
5. In the dialog box, select where you want to save your file, and then click Save.

Log files tool

Viewing logs

Viewing log files in an external log viewer

You can view log files using an external log viewer, such as Kibana. An external log viewer can help you
visualize logs and monitor potential issues.

The external log viewer must be installed and its URL configured on the Resource URLs tab of the System
Settings landing page before you can use it.
 1. Click Configure System Operations Logs .
2. Click External Log Viewer.

Result: Note: If the log viewer has not been configured, click Configure URL to specify the log viewer's
URL.

Configuring resource URLs

Viewing logs

Log levels for log categories

You can select which log messages your log files include by creating log categories and associating log
levels with your categories.

The log level of a category determines the type of messages that the log file includes. When you create a
log category and set its default log level, these selections apply to all nodes in the cluster and they persist
until you change them. The default log level applies to all the loggers that you associate with your category.

Log levels
When you choose a log level, messages from that level and above are written to the log file. For example, if
the log level is set to ERROR, the log file includes log messages with a severity of ERROR and FATAL. The
following list orders log levels from highest (most severe) to lowest (least severe):

OFF
The log file does not include any messages.
FATAL
The log file includes messages that inform about severe errors that can cause the application to
terminate.
ERROR
The log file includes messages that inform about serious errors that might allow the application to
continue running.
ALERT
The log file includes Pega Platform -specific messages that indicate that a performance threshold has
been exceeded, or that an event that affects the performance has occured.
WARN
The log file includes messages that inform about situations that might have an adverse performance
implication.
INFO
The log file includes messages that inform that a run-time event, such as startup or shutdown, has
occurred.
DEBUG
The log file includes messages that inform about informational events that are useful for debugging.
ALL
The log file includes messages of all levels.

Note: Adjust a log level to your specific needs. The log level that is too verbose may cause performance
issues.

You can apply the same log levels to individual loggers. For example, if you want a log category that groups
loggers that correspond with agents to work on the FATAL level, but you need one logger within this
category to work on the ALL level, you can change the level of the individual logger.

Creating log categories

Creating log categories

Structure log messages into categories by creating custom log categories. Grouping loggers into categories
makes it easier to manage log levels of loggers, because you do not have to remember the names of
individual loggers.

Before you begin: To edit log categories, you must have the pzLogLevelAdministrator privilege.

1. In Dev Studio, click Records SysAdmin Log Category , and then click Create.
 2. Enter a short description and a logger category name, and then click Create and open .
3. Enter a description of your log category.
4. From the Log Level dropdown list, select a default log level for your category.
The default log level determines which log messages are written to the log file and applies to all the
loggers associated with the category. For more information, see Log levels for log categories.
5. Associate loggers with your category by clicking +Add logger and entering logger names in the
Logger Name field.
6. Click Save.
For more information about log categories, see Log categories on Pega Community.

Logging Level Settings tool

You can use the Logging Level Settings tool to temporarily override the severity settings in the prlog4j2.xml file
for the current node and control which logging events are displayed in the Pega log. For example, you can
change the logging level for activities in the Work- class from FATAL to DEBUG for troubleshooting purposes.

When you change the logging level, the system adds an entry in the Pega log that includes your operator ID
and the date and time of the change.

Logging level changes take effect immediately and remain in effect until the node is stopped, or until the
level is changed again by using the Logging Level Settings tool. The prlog4j2.xml file is not updated. Logging
operations on nodes other than the current node are not affected.

Log messages that are generated by the Log-Message method statement and oLog() calls in Java steps are
written to the log files. The log message level for a particular message is determined by your code. The
logging level that is set in the Logging Level Settings tool determines which messages are written to the log
file.

You an access the Logging Level Settings tool by clicking Configure System Operations Logs Logging
level settings .

Logging levels
Each level causes messages of that level and above to be written to the log file. Following are the possible
logging levels, listed from highest (most severe) to lowest (least severe):

OFF – Turns off logging.

FATAL – Indicates severe errors that can cause the application to terminate.
ERROR – Indicates serious errors that might allow the application to continue running.
ALERT – Pega Platform-specific messages that indicate that a performance threshold has been
exceeded, or that an event has occurred that has an adverse performance implication.
WARN – Indicates situations that might have an adverse performance implication.
INFO – Indicates that a run-time event, such as startup or shutdown, has occurred.
DEBUG – Indicates informational events useful for debugging.
ALL – Indicates that all messages are logged.

For example, if the logging level is set to ERROR, log messages with a severity of ERROR and FATAL are
written to the log file.

Rulesets, class hierarchy, and loggers

A logging level can be set for a specific Java class or other logger category. Rulesets and Pega Platform
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),
if any of these activities are run on the current node, they might produce logged events.

Temporarily changing the logging level

You can use the Logging Level Settings tool to support debugging by temporarily overriding the
logging level settings in the prlog4j2.xml file for the current node.

Resetting the logging level for all loggers

You can reset the logging level for all loggers to the settings in the prlog4j2.xml file. By resetting all
 loggers you avoid resetting loggers individually. This setting is useful when you have changed settings
for several loggers during debugging and you want to set them back to their original values. All
changes to logging levels that are made by any operator using the Logging Level Settings tool are
reset.

Viewing logs
Troubleshooting tools and techniques

Temporarily changing the logging level

You can use the Logging Level Settings tool to support debugging by temporarily overriding the logging
level settings in the prlog4j2.xml file for the current node.

1. Click Dev Studio System Operations Logs Logging level settings .

2. In the Logger Name field, press the Down arrow key to list all Java classes in com.pega.pegarules and
select the Java class that you want to change, or enter a logger category:
To review or update the logging level for all activity executions, enter Rule_Obj_Activity.
To update the logging level for all activities with the given name in any Applies To class, enter
Rule_Obj_Activity.<activity name>, and then press the Down arrow key and select a logger name.

You can view the logger name of an activity by opening the activity and clicking Actions View
Java . The logger name of the activity is in a Rule_Obj_Activity.<activity name> format.

To update the logging level for all agents, enter com.pega.pegarules.engine.context.Agent.

3. In the Current Level field, click the logging level for the selected class.
4. Exit the dialog box.

Resetting the logging level for all loggers

Resetting the logging level for all loggers

You can reset the logging level for all loggers to the settings in the prlog4j2.xml file. By resetting all loggers
you avoid resetting loggers individually. This setting is useful when you have changed settings for several
loggers during debugging and you want to set them back to their original values. All changes to logging
levels that are made by any operator using the Logging Level Settings tool are reset.

1. Click Dev Studio > System > Operations > Logs > Logging level settings.
2. Click Reset all loggers to default settings .

Log-Message method

Renaming Pega logs

If two or more Pega Platform servers are installed in a single application server instance, they write lines to
a common Pega log file. To prevent this from occurring, you can change the name or path of the Pega log
for a node by modifying the prlog4j2.xml file.

In the following example, the log file name starts with PEGABLUE:

filePattern="${sys:pega.tmpdir}/PegaBLUE-%d{MM-dd-yyyy}-%i.log.gz">

Viewing logs

Rolling a log file

You can update the prlog4j2.xml file or dynamic system setting to cause a new log file to be created at the start
of each day or on a periodic basis, rather than only at startup. This is known as "rolling" the log file.

Log file appenders

Pega Platform uses the RollingRandomAccessFileAppender from Log4j 2 as the default file appender.
You can use a different log file appender. For more information, refer to the Log4j 2 documentation.

Log file appenders

Pega Platform uses the RollingRandomAccessFileAppender from Log4j 2 as the default file appender. You
can use a different log file appender. For more information, refer to the Log4j 2 documentation.

Rolling a log file

Displaying node type in the log

You can optionally choose to display the system node type in the Pega Platform log.

The system node type is available for display in the Pega Platform log, although by default it is not shown.
To display the node type in the Pega Platform log, configure the PatternLayout for your log to render the
nodeType property. For more information, refer to the Apache Log4j 2 documentation for PatternLayout.

My Alerts display
You can view the current Alert log on the server node produced by your own requestor session by using the
My Alerts display. Select Issues from the Dev Studio developer toolbar.

Note: This display is limited to the current Alert log; alerts in older logs are not visible. Depending on your
log file system settings, a new log may start each time a node is started, at a specific time each day, or on
some other basis.

The following summary information is displayed for each alert:

Date and Time – Date and time of the alert, converted from GMT to the time zone of the server.
Alert Type – A text description of the alert type. For example, the text BrowserInteraction corresponds to
alert type PEGA0001, interaction times. Other types are Database (PEGA002 to PEGA007) .
Value – The measured value of the Key Performance Indicator, recorded in seconds, as a count, or in
bytes.
Interaction – The sequence number of the browser-to-server interaction since the requestor session
began, as indicated by the Performance tool display.
Work Pool – Work pool that the requestor is using, or none.
Last Input – A portion of the URL received in the most recent interaction. Typically the text Stream=
or Activity= and the name of an activity or stream rule run by the URL.
First Activity – For alerts from interactive requestors, the first activity or stream run by this requestor
in the current interaction. (This activity or stream may or may not have caused the alert.)

The alerts are ordered by date and time; the first row is the most current. Click the arrow in the first column
to expand the row to view more details about the alert.

Note: When using this tool for Customer Service chat interactions, be aware that a single browser session
can be served by multiple requestors.

Display options
By default, 20 alerts are displayed on the page.

Click a numbered link, next>, or <previous to scroll back and forth through the list.
Click This Session Only to limit the display to alerts produced by your current requestor session.
Click All My Sessions to include alerts from the current session and other sessions with your current
Operator ID.
Click Performance or Security to toggle the display between security-related alerts (SECnnnn) and
performance-related events (PEGAnnnn).
Click the Options link to view or set log filtering criteria. You can set the following options:
Lines per page – Enter the number of alerts to display on a page. The valid values are 1 through
200.
Number of pages presented – Set a maximum number of pages to present as numbered links,
between 2 and 20.
Filter by – Optional. Enter a text string to limit the display to only alert lines containing an exact
match anywhere within the line. Leave blank for no filtering. Case is not significant. For example,
enter Smith@Alpha.com to find lines containing this value, or containing SMITH@alpha.com.
Click Apply to update the display with the new filter criteria.

Parsing the alert log

 You can import the alert log into Microsoft Excel for viewing, searching, sorting, or other analysis using
the Text Import Wizard in Microsoft Excel. Fields in the alert log are delimited by an asterisk.

Suppressing sensitive data in alerts

The alert log identifies the names of activities and other rules that have been executed. By default,
PEGA0002 to PEGA0007 alerts also show parameter values and SQL statements containing property
values. You can include the suppressInserts and includeParameterPage keywords in the prconfig.xml
file so that parameter values and other potentially sensitive data values are omitted in prepared
statement inserts:

Summarizing the alert log

You can parse, consolidate, and summarize alert logs using the PegaRULES Log Analyzer or services
such as Elastic Stack.

Alerts

You can view or download the current alert log to see important notifications about the functioning of
your system.

Alert format

Each line of the log contains multiple fields, delimited by a single asterisk character. Each line contains
the following fields. The first column of the table is the Excel column after you have imported the file
into Excel.

Parsing the alert log

You can import the alert log into Microsoft Excel for viewing, searching, sorting, or other analysis using the
Text Import Wizard in Microsoft Excel. Fields in the alert log are delimited by an asterisk.

1. Start Microsoft Excel.

2. Click File Open .
3. Navigate to the PEGA-ALERT-ZZZZ.log file and click Open.
4. Click Delimited in the Original data type group.
5. Click Next.
6. Select Other.
7. Enter a single asterisk as the delimiter.
8. Click Next.
9. Click Finish.

Alert format
Summarizing the alert log

Suppressing sensitive data in alerts

The alert log identifies the names of activities and other rules that have been executed. By default,
PEGA0002 to PEGA0007 alerts also show parameter values and SQL statements containing property values.
You can include the suppressInserts and includeParameterPage keywords in the prconfig.xml file so that parameter
values and other potentially sensitive data values are omitted in prepared statement inserts:

For a complete list of alert log settings, refer to the Pega Community article Security settings in the
prconfig.xml file.

1. Add the following to the prconfig.xml file:

<env name="alerts/database/operationTimeThreshold/suppressInserts"
value="true" />
<env name="alerts/general/includeParameterPage" value="false" />

2. Stop and restart or redeploy the system.

Alerts
Parsing the alert log
Summarizing the alert log
 Alert format

Summarizing the alert log

You can parse, consolidate, and summarize alert logs using the PegaRULES Log Analyzer or services such
as Elastic Stack.

For information on the PegaRULES Log Analyzer, see the Pega Community articles Understanding the
PegaRULES Log Analyzer and How to use the PegaRULES Log Analyzer .

Alerts
Parsing the alert log
Suppressing sensitive data in alerts
Alert format

Alerts
You can view or download the current alert log to see important notifications about the functioning of your
system.

Threshold settings in the prconfig.xml file or dynamic system settings affect the operation and criteria of
many alerts. A setting in the prlog4j2.xml file determines the name and existence of the alert log.

For a list of performance and security alerts in Pega Platform, see the List of performance and security
alerts in Pega Platform on Pega Community.

My Alerts display
Alert format
Parsing the alert log
Suppressing sensitive data in alerts
Summarizing the alert log
Configuring dynamic system settings

Alert format
Each line of the log contains multiple fields, delimited by a single asterisk character. Each line contains the
following fields. The first column of the table is the Excel column after you have imported the file into Excel.

Column Field Description

Time
A Date and time of the alert event in UTC format.
stamp

B Version Displays the header version for the alert. For example, "8".

C Message ID Identifier of alert type, for example PEGA0011.

Observed duration in milliseconds or count of value, known as the key

D KPI Value
performance indicator.

KPI
E Threshold value for this alert type, in milliseconds or count.
Threshold

F ServerID Node ID for the node that is the source of the alert event.

Session identifier; the first letter (A, B, H, or P) identifies the requestor type.

A - requestor is being used by an application

Requestor
I B - batch requestor used by agent processing
ID
H - requestor is being used by a user (HTTP interaction)
P - requestor is used for portlet support

J User ID Operator ID of requestor, or none.

K Work pool Work pool that the requestor uses, or none.

Column Field
Rule Description
application
L Rule application and version used at the time of the alert.
name
version

Encoded
M Hash code identifying the requestors ruleset list.
Ruleset

Checkout Y indicates that the activity in the Activity field is in a personal ruleset; that a
N
Enabled developer has checked out the activity.

Interaction For alerts from browser sessions, the interaction number (as it appears on the
O
number Performance tool display).

Correlation ID used to filter messages arriving on the request queue. By default, the requestor
P
ID ID.

Q Sequence Sequence number for this alert in the log; unique within this log.

R Thread Internal name of the PRThread instance, or NA if this alert is not from a Thread.

Pega
S Thread The name of the Pega thread on which the alert happened.
Name

T Logger Java class that produced the alert instance.

An indicator in the engine process that shows the processing state when the
U Stack
message occurred. (Not available for all alerts.)

For alerts from interactive requestors, a portion of the URL received in the most
V Last Input recent interaction. Typically the text Stream= or Activity= and the name of an
activity or stream rule run by the URL.

For alerts from interactive requestors, the first activity or stream run by this
First
W requestor in the current interaction. (This activity or stream may or may not have
Activity
caused the alert.)

If the First Activity field identifies an activity, this field identifies the step number
X Last Step
last completed, when available.

Y Reserved Reserved.

Z Reserved Reserved.

AA Reserved Reserved.

AB Reserved Reserved.

Colon-delimited string containing the most recent 50 operations of this requestor

AC Trace List before the alert event. Each operation consists of two subfields in the format
number:value:.

For some Message ID types, a set of selected of Performance tool statistics at the
AD PAL data time of the alert. A colon delimited string in the format propertyname:value:.
Values are in milliseconds, bytes, or counts.

Primary
AE The class of the primary page at the time of the alert.
page class

Primary
AF The name of the primary page at the time of the alert.
page name

Step page
AG The class of the step page at the time of the alert.
class

Step page
AH The name of the step page at the time of the alert.
name
 AI
Column Pega stack
Field The Pega stack at the time of the alert.
Description
Parameter
AJ The clipboard page data found on the parameter page at the time of the alert.
page

AK Line A text description of the alert.

Parsing the alert log

Viewing and resolving errors

Errors appear if you save a form and the system detects one or more errors.

You must correct any errors before you can save the form by completing the following steps:

1. Use the information displayed in the error section of the header to understand what the issue is and
how to resolve it.
2. Use the indicator icons to quickly see which tab has an issue and what fields on that tab are involved
in the error condition.
3. Make your changes to the affected areas on the form and click Save.
The header automatically updates to reflect the new error count. After you resolve all errors, errors no
longer appear in the header, and you can save the form.

Viewing in-progress and completed wizards

You can find all wizards that have been started on the All Wizards landing page. You can use this landing
page to clean up incomplete wizards.

1. In Dev Studio, click Configure Application Tools All Wizards .

2. Enter keywords in the fields to filter results. By default, only unfinished wizards are listed.
3. Click a wizard name to open it.
4. Follow the steps of the wizard to resolve it.

Creating connector simulators

With the Connect Simulator functionality, test connect rules in flows and from data pages before the actual
data source is implemented, or when it is not available.

To simulate a connector:
1. Create an activity that sets values to the properties that are to be returned by the connector. For more
information, see Creating an activity.
2. On the Service tab of the Connector rule form, click the Simulations button to access the
Simulations form.
3. On the Simulations form, click Add a row.
4. To enable simulation, in the Simulation Activity field, enter or select an activity.
5. Select either the Global or User Session options.
6. Click Submit.

When flow execution reaches the connector shape, the activity is called.

Disabling simulations
When you no longer need to simulate the connector, you can temporarily ignore all simulators by accessing
the Connect Simulator window and clicking the Clear Local or Clear Global buttons.

You can also disable or enable simulations on the Connectors landing page.

Connect Simulator Properties

Field Description

Simulation Activity name (second key part) of an activity that simulates the results of the connector
 Activity
Field rule identified by the previous fields in this row.
Description

Enables system-wide use of the simulator whenever flow execution reaches the connector
Global shape. When enabled along with a User Session, the User Session overrides the Global
simulator.

User The simulation occurs only when the flow is started by the logged-in user. The User Session
Session overrides a Global simulator.

Remove the Simulation Activity.

Clear
Click to clear the User Session option from all Simulation Activities.
Local

Clear Click to clear the Global option from all simulation activities. This option is not available if
Global the production level of the system is 5.

Apply
Click to apply changes to the Connect Simulator.
Changes

Close Click to close the Connect Simulator form.

Example
For an example of a connector simulation, see the Pega Community article How to simulate a SOAP
connector.

Integration Resources category

Testing regular expressions

Use the Regular Expression tester to test whether a text pattern matches the regular expression.

1. Use the Application Explorer to open the standard activity Code-Pega-Parse.RegExpTester.

2. Click Actions Run . A test input form appears.
3. In the Page list, click Empty test page .
4. Leave the parameter values blank. Click Run.
5. Complete the detail form.
Field Description

Regular Enter a regular expression to be used, using syntax conforming to the Java
Expression implementation of regular expressions Java.util.regex.Pattern.

Source Enter source text to be searched for matches to the regular expression.

Select to recognize only newline characters (\n, also called line feed) as end-of-line
delimiters. Clear to recognize additional characters or character pairs as end-of-line
UNIX Lines
delimiters: carriage return (\r), carriage return followed by newline, next-line
(\u0085), line-separator (\u2028) and paragraph-separator (\u2029).

Select to cause the expressions ^ and $ to match immediately after or immediately

before, respectively, a line terminator or the end of the input sequence.
Multilines
Clear to have these expressions only match at the beginning and the end of the
entire input sequence

Select to cause two characters to considered to match if, and only if, their full
canonical decompositions match.
Canonical
Equivalence The expression "a\u030A", for example, matches the string "?" when this flag is
specified. By default, matching does not take canonical equivalence into account.

Select to ignore all white space (tabs and spaces) within the Source text, and to
Comments
ignore all material starting with a comment character # through the end of the line.
 Field Description
Select to indicate that a period character is to match any character including a line
Dot
terminator. Clear to indicate that a period character is to match any character except
Matches All
a line terminator.

ASCII Case
Select to match uppercase with lowercase ASCII characters.
Insensitive

Unicode
Case Select to match uppercase with lowercase ASCII characters.
Insensitive
6. Click Test Expression.
7. A table of results lists each match of the regular expression found in the Source text.

Regular Expression rules

The DateTime parse tester tool

Use the Date/Time Parse Tester tool to test whether a text input matches the DateTime patterns used by
Pega Platform, which are based directly on Java standards.

1. Use the Application Explorer to open the standard activity Code-Pega-Parse.DTParseTester.

2. Click Actions Run . A test input form appears.
3. In the Page list, click Empty test page .
4. Leave the parameter values blank. Click Run.
5. Complete the input fields on the form:
Field Description

Enter a pattern. The count of pattern letters identifies a format:

G — Era designator, for example AD
y — Year, for example 2018
M — Month in year, for example July or 07
d — Day in month, for example 10
Date/Time h — Hour in A.M./P.M. format, 1 to 12
Pattern H — Hour in day format, 0 to 23
m — Minute in hour, for example 30
s — Second
S — Millisecond
E — Day in week, for example Tuesday
Z — Time zone, for example Pacific Standard Time

Test Case Enter text that may contain a date or date/time formatted with the pattern.

Select:
Locale Use default locale — The current locale of your requestor session is used.
Specify a locale — Select a locale from a list.

Select:
Use default timezone — The current locale of the server node is used (not the
Timezone
time zone in your workstation or operator ID instance)
Specify a timezone — Select a locale from a list.
6. Click Test Parsing.
7. The system searches the Test Case text for a conforming date or date/time value. If found, it converts
the value into a Pega Platform internal format and displays the results.

Internationalization and localization

About the bulk Revalidate and Save tool

You can force revalidation in bulk of selected rule or data instances of a single type.

For example, you can revalidate all operator ID instances, or all flows in a specific RuleSet and version.

The Revalidate and Save tool is useful in various situations, including the following:
 After you import a .zip file archive of rules that may depend on rules previously present, or that were
exported from a lower-version Pega Platform system.
To confirm that rules pass current validation requirements.
To propagate the effects of changes you made to some rules to other rules that reference those rules.

This operation is similar to opening and then saving each selected rule or data instance. If an instance fails
validation, the previous version is unchanged.

Every saved rule or data instance was previously validated at least once, at the time it was most recently
saved. The instance was valid at that time in the environment, system, and context in which it was saved.
Revalidation is desirable to confirm that nothing in the current environment makes the object invalid.

If an instance passes validation, the History tab is updated with your operator ID, the current date and time,
and current system in the Updated row. For rules, a history detail instance is added with your memo and
the notation Bulk Update.

Starting the bulk revalidation tool

To revalidate rule or data instances:

1. In Dev Studio, click Configure System Release Upgrade Validate .

2. Complete the form. See Help — Using the Revalidate and Save tool for instructions.
3. Click Run to begin revalidation.
4. As it executes, the Revalidate and Save tool marks valid rules (or data instances) with a checkmark;
rules not valid are marked with a red X. Hold the mouse pointer over the red X to see the error
message. Click the Open icon to open the instance.

Note:

If an instance fails validation, the previously saved instance remains and is unmodified.
Depending on the number of rules or data instances selected, this processing may require minutes or
hours to complete.
Note any rule or data instances that fail validation. After making corrections, you can click Clear
Status and rerun the test.
For some rule types, validation of an instance may fail because another instance is invalid. Running
the Revalidate and Save tool a second time may allow instances that failed the first time to validate.
You can revalidate rules that belong to a locked RuleSets version, excluding RuleSet versions that
form the Pega Platform product. The History tab and history details are updated to reflect a successful
revalidation; other aspects of the rule (as visible on the form) do not change.
Some rules may present warning messages. Warning messages do not indicate that the rule failed to
validate or save. Use the Guardrails landing page to see rules that have warnings.
For an automated approach, see the Pega Community article How to revalidate all rules in a RuleSet .

Validation tool

Use the Validation tool to check the validity of rules in your application. This tool ensures that all rules
defined in an application are valid and contain valid rule references based on a specified application
context.

Using the Revalidate and Save tool

You can identify the class of the instances (such as rules or data instances) to be revalidated, and
optionally a RuleSet and Version, and list instances that meet these criteria. You can also bulk validate
the rules you select.

Validation tool
Use the Validation tool to check the validity of rules in your application. This tool ensures that all rules
defined in an application are valid and contain valid rule references based on a specified application
context.

The Validation tool can help you improve the quality of your application and should be used regularly. It is
available for rulesets using both Application Validation (AV) mode and Ruleset Validation (RV) mode. See
Application Validation mode.
Use the Validation tool:

To identify how changes to some rules will impact other rules that reference those rules. For example,
if you delete or change the return type of a rule by running the Validation tool, you will know how
many rules became invalid by that change.
To confirm that rules pass current validation requirements
After critical changes or milestones, such as:
Changes to a ruleset list in the application rule
Changes to a built-on application
Before lock/export
After import
Regularly during development

How the Validation tool works

The Validation tool is available only to users who have access to the ApplicationValidation privilege. The
access role PegaRULES:SysAdm4 provides these privileges. The tool will quickly validate the rules in your
application, ruleset, or ruleset version without re-saving them. Only rules that can be called at runtime are
validated; withdrawn and circumstanced rules are not validated.

To run the Validation tool

1. Click Configure Application Tools Validation .

2. Select the application or individual ruleset and (optionally) the version you want to validate from the
Select Validation drop-down menu.

3. Click Run Validation to begin validation.

A progress bar appears, indicating:

Total rules – Number of rules associated with application

Processed Rules – Number of rules validated at given point in time
Invalid Rules – Number of invalid rules found at given point in time

Click Cancel at any time to stop the execution of the validation process.

You can only run the Validation tool for the selected application. To run for another application, click the
Reset Validation button.

Once validation is complete, a results grid displays a list of any rules that failed validation, along with their
associated error messages.

Expand a rule name to display the rule’s validation error.

Click the Rule Name to open the rule.

Note: When you open the rule from the results grid, it will not contain the error messages from the
validation process. To re-validate the rule, save the rule.

Application Validation mode ruleset

Using the Revalidate and Save tool

You can identify the class of the instances (such as rules or data instances) to be revalidated, and optionally
a RuleSet and Version, and list instances that meet these criteria. You can also bulk validate the rules you
select.

Completing the form

Complete this form to identify the objects to be revalidated.

Label Description

Class Select the type of object to be listed.

 Label
RuleSet Optional. If you chose a rule type, youDescription
many select a RuleSet to restrict which the rules
Name are listed.

If you selected a RuleSet Name, select to limit the rules to be listed to a single version.
RuleSet
Version Select a version number.

If you selected a version number, select to cause the revalidated rules to be placed in a
During higher version number. Rules that fail validation are not altered.
Update
Move to? Select the new version number, from those already defined for the selected RuleSet.

Enter a brief text memo describing the purpose of this bulk revalidation. This memo
Memo
appears in the detailed history of instances that are successfully revalidated.

List Click to list the objects that meet the criteria you have entered.

Run Click to begin processing the selected instances.

Close Click to close the Revalidate and Save form.

Controls
Columns of the list include an Update? check box, the key of the object, a RuleSet and version (for rules),
and the status. Check at least one box before starting the bulk validation:

Select the Update? check box for a row to include this row in the validation.
Click Check All to check the Update? box in all rows.
Click Uncheck All to clear the Update? box in all rows.
Click Inverse to invert the Update? box value in all rows.

Click Run to begin revalidation. Click Stop to pause revalidation. Results are presented in the Results
column as a check mark or red X. Hold the mouse pointer over the red X to review at least one error.

Click the Open icon in any row to review or correct any that fail.

After making corrections, you can click Clear Status and rerun the validation test.

Results
A dynamic display identifies the key of the object being processed; a counter shows total rows and rows
that failed validation.

This operation is similar to opening and saving each rule or data instance. (In addition, some but not all
RuleSet prerequisites and class restrictions are checked.) If an instance fails validation, the previous saved
version is unchanged.

If an instance passes validation, the History tab is updated with your operator ID, the current date and
time, and current system in the Updated row. For rules, a history detail instance is added with your Memo
and the notation Bulk Update.

Warning messages may appear. Warning messages do not indicate that the rule failed to validate or save.
Use Guardrails landing page to see all warnings.

You can revalidate rules that belong to a locked RuleSets version, excluding RuleSet versions that form the
Pega Platform. The History tab and history details are updated to reflect the successful revalidation; other
aspects of the rule (as visible on the form) do not change.

About the bulk Revalidate and Save tool

Application Structure landing page

The Application Structure landing page helps you to manage and understand the rulesets, rules, access
groups, and operators that make up your Pega Platform application. Options on this page display
referencing applications, allow you to invite collaborators to the development process, and provides access
to other applications on the system (for operators with permission to do so).

Access this landing page from Dev Studio by clicking Configure Application Structure .

RuleSet Stack tab

Access the RuleSet Stack tab by clicking Configure Application Structure RuleSet Stack .

RuleSet Prerequisites tab

Access the RuleSet Prerequisites tab by clicking Configure Application Structure RuleSet Prerequisites .

Referencing Applications tab

Access the Referencing Applications tab by clicking Configure Application Structure Referencing
Applications .

Access Groups & Users tab

Access the Access Groups & Users tab by clicking Configure Application Structure Access Groups And
Users .

Other Applications tab

Access the Other Applications tab from the header of Dev Studio by clicking Configure Application
Structure Other Applications .

RuleSet Stack tab

Access the RuleSet Stack tab by clicking Configure Application Structure RuleSet Stack .

This tab lists the rulesets and ruleset versions that make up your current application including those
inherited from any built-on applications. It also allows you to lock versions and roll (increment) them to
higher versions.

The display is organized by Current Application followed by the Built on Application(s) and is filtered by
ruleset and version, lock status, total number of rules, and number of checked out rules.

To open an application rule in the list, click its name.

Field Description

RuleSet The rulesets and versions in the application. To open a ruleset, click its name.

Contains an icon indicating the lock status of ruleset versions for the application.

— Indicates that the version for any given ruleset is locked. Also indicates a locked
application rule.
— Indicates that the version for any given ruleset is unlocked. Also indicates an
unlocked application rule.
— Warns you that a locked ruleset version has lower unlocked versions. Click the
icon to view a list that shows you which versions are unlocked. To lock an unlocked
version, select it in the list, and its rule form opens where you can lock the version. As a
Lock best practice, leave only the highest version of a ruleset unlocked. If the warning
condition exists, you cannot roll (increment) a lower unlocked version using Lock and Roll
functionality.
— Warns you that this ruleset version does not exist but appears in your application
rule. To correct, remove the version.

Click an icon to open a window that displays a list of versions, and for each version, the lock
status and the number of total and checked out versioned and non-versioned rules, including
ruleset, class, and organization instances.
 Checked
Field The total number of checked-out versioned and non-versioned rules.
Description
Out

The total number of versioned and non-versioned rules. Click a number to open a window
All
listing the rule types and counts comprising the total. Click a row (including Total) in the list to
Rules
drill down to a list of rule instances comprising a rule type.

Click to display the Application Lock and Roll window where you can review, lock current
Lock ruleset versions, and roll (increment) versions in a single step. You can optionally update your
and Roll current application rule to reflect the new versions, or create a new application rule that
contains the new ruleset versions.

Package
For the Current Application only. Click to start the Application Package wizard, to create a
and
product rule for this application. See About the Application Package wizard.
Export

In the window, select the application ruleset versions you want to lock and roll to a higher version.

Field Description

Select the check box to indicate you want to lock the ruleset version and roll to a new
version. Locking prevents a developer from saving new rule instances to this version, or
updating or deleting existing instances.

Lock A icon appears if there is a condition that might prevent you from locking the ruleset
version. For example: A higher locked version exists or a version currently has rules
checked out.

A icon appears if the ruleset version is already locked.

The ruleset and current version.

Click the + icon next to the Prerequisites label to display the Current and New
prerequisites for the version. To open the rule form for a current ruleset and version, click
its name in the Current list.
RuleSet When you lock a ruleset version and select the Roll check box, you can modify the new
Version prerequisites. By default, they are the same as the current ones. You can select different
prerequisites, add additional ones, and delete ones from the New list. To add another
ruleset version to the list, click the Add a row icon. To open the rule form for a ruleset in
the New list, click the Open the Rule Form icon next to its name. To delete a ruleset
from the New list, click the Delete icon next to its name.

Password Appears when you select the Lock check box. Enter the password for the ruleset version.

Roll Displays when Lock is selected. Used to roll the ruleset to a higher version.

Roll to Displays the version that the ruleset will be rolled to unless you indicate another version
Version number. Defaults to the next logical number in the ruleset numbering sequence.

Description Current description of the ruleset version.

Select an option to run against the selected ruleset versions.

Do not update my application — Locks and rolls the versions without updating the
application ruleset list.
Update my Application to include the new RuleSet Versions — Locks and rolls
the versions and updates the current application ruleset list. Prompts with an
application description (current by default, which you can edit). Also prompts for a
Run
password if the current application is locked. Enter the application password.
Create a new version of my Application — Locks and rolls the versions and
creates a new application rule. Prompts with the new application version (one
increment higher by default, which you can edit), and with an application description
(current by default, which you can edit). Also prompts for a password if the current
application is locked. Enter the application password.
 Field Description
Application Structure landing page

RuleSet Prerequisites tab

Access the RuleSet Prerequisites tab by clicking Configure Application Structure RuleSet
Prerequisites .

This tab displays a tree view of rulesets and versions and their prerequisites in the current application.

Click the + icon to expand the tree to show the prerequisite rulesets and versions. A version in blue
text indicates that it is listed as a top-level version in the application ruleset list.
Click the name of a ruleset in the tree to open and view its ruleset form.

Note: Rulesets using Application Validation mode do not have prerequisites.

Application Structure landing page

Application Validation mode ruleset

Referencing Applications tab

Access the Referencing Applications tab by clicking Configure Application Structure Referencing
Applications .

This tab lists other applications that reference the current application.

Field Description

Name and Version This (referencing) application name and version.

The total number of access groups associated with this

Access Groups
application.

Operators The total number of operators associated with the access groups.

RuleSet This application ruleset.

Application Structure landing page

Access Groups & Users tab

Access the Access Groups & Users tab by clicking Configure Application Structure Access Groups And
Users .

Use this tab to:

See the list of access groups that provide access to the current application.
See the list of users that belong to an access group.
Invite people to collaborate in developing this application.

Field Description

Click to invite people (via email) to collaborate in developing the application. For
example, a Lead Business Analyst can invite other business analysts to edit and add
specifications and requirements to the in-progress application. They might also invite
Invite subject matter experts to review the specifications.
Collaborator
Upon clicking the link, the Invite Collaborator window opens for you to specify the
information needed to send email invitations to the invitees. See Invite Collaborator
window — Inviting collaborators.

Access The name of an access group referenced by the application. Select a name to see the list
 Group
Field of users that reference that access group, and so have that level of access into the
Description
application.
Operator
The names of operators who reference the access group.
Name

Operator ID The IDs of operators who reference the access group.

Application Structure landing page

Other Applications tab

Access the Other Applications tab from the header of Dev Studio by clicking Configure Application
Structure Other Applications .

Administrators (operators with the PegaRULES:SysAdm4 role or a role based on that role) can use this tab
to lock and roll applications in the Pega Platform system other than those in the ruleset stack of the current
application. For example, when upgrading a Pega Platform it is considered best practice to lock all
applications and create new ruleset versions before resuming development.

This page displays all applications in the system that contain an unlocked ruleset version and lists the
rulesets and ruleset versions that make up each application including those inherited from any built-on
applications.

To open an application rule in the list, click its name.

Field Description

RuleSet The rulesets and versions in the application.

Contains an icon indicating the lock status of ruleset versions for the application.

— Indicates that the version for any given ruleset is locked. Also indicates a locked
application rule.
— Indicates that the version for any given ruleset is unlocked. Also indicates an
unlocked application rule.
— Warns you that a locked ruleset version has lower unlocked versions. Click the
icon to view a list that shows you which versions are unlocked. To lock an unlocked
version, select it in the list, and its rule form opens where you can lock the version. As a
Lock best practice, leave only the highest version of a ruleset unlocked. If the warning
condition exists, you cannot roll (increment) a lower unlocked version using Lock and Roll
functionality.
— Warns you that this ruleset version does not exist but appears in your application
rule. To correct, remove the version.

Click an icon to open a window that displays a list of versions, and for each version, the lock
status and the number of total and checked out versioned and non-versioned rules including
ruleset, class, and organization instances.

Checked
The total number of checked-out versioned and non-versioned rules.
Out

The total number of versioned and non-versioned rules. Click a number to open a window
All
listing the rule types and counts comprising the total. Click a row (including Total) in the list to
Rules
drill down to a list of rule instances comprising a rule type.

Click to display the Application Lock and Roll window where you can review, lock current
Lock ruleset versions, and roll (increment) versions in a single step. You can optionally update your
and Roll current application rule to reflect the new versions, or create a new application rule that
contains the new ruleset versions.

In the window, select the application ruleset versions you want to lock and roll to a higher version.

Field Description
 Field Select the check box to indicate you want to lock the ruleset version and roll to a new
Description
version. Locking prevents a developer from saving new rule instances to this version, or
updating or deleting existing instances.

Lock A icon appears if there is a condition that might prevent you from locking the ruleset
version. For example: A higher locked version exists or a version currently has rules
checked out.

A icon appears if the ruleset version is already locked.

The ruleset and current version. Note: Rulesets using Application Validation mode do not
have prerequisites.

Click the + icon next to the Prerequisites label to display the Current and New
prerequisites for the version. To open the rule form for a current ruleset and version, click
its name in the Current list.
RuleSet
Version When you lock a ruleset version and select the Roll check box, you can modify the new
prerequisites. By default, they are the same as the current ones. You can select different
prerequisites, add additional ones, and delete ones from the New list. To add another
ruleset version to the list, click the Add a row icon. To open the rule form for a ruleset in
the New list, click the Open the Rule Form icon next to its name. To delete a ruleset
from the New list, click the Delete icon next to its name.

Password Appears when you select the Lock check box. Enter the password for the ruleset version.

Roll Displays when Lock is selected. Used to roll the ruleset to a higher version.

Roll to Displays the version that the ruleset will be rolled to unless you indicate another version
Version number. Defaults to the next logical number in the ruleset numbering sequence.

Description Current description of the ruleset version.

Select an option to run against the selected ruleset versions.

Do not update my application — Locks and rolls the versions without updating the
application ruleset list.
Update my Application to include the new RuleSet Versions — Locks and rolls
the versions and updates the current application ruleset list. Prompts with an
application description (current by default, which you can edit). Also prompts for a
Run
password if the current application is locked. Enter the application password.
Create a new version of my Application — Locks and rolls the versions and
creates a new application rule. Prompts with the new application version (one
increment higher by default, which you can edit), and with an application description
(current by default, which you can edit). Also prompts for a password if the current
application is locked. Enter the application password.

Application Structure landing page