Low-code application development

Turn creating applications into a low-code and user-friendly experience by using 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.

Getting started with low-code application development

Start building your applications in a user-friendly and seamless way by implementing low-code digital
solutions. Design your unique journey to achieve your goals faster and with greater effect. 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.

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.

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.

Getting started with low-code application development

Start building your applications in a user-friendly and seamless way by implementing low-code digital
solutions. Design your unique journey to achieve your goals faster and with greater effect. 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.

Exploring application

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

Building your first application

Start developing your projects in a convenient and simplified way by building your first application
from a template. When you create an application, you can save time by reusing default and existing
elements.
 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.

Understanding project roles and personas

Creating a Microjourney for customer success
Designing applications for reuse and extension
Engaging with stakeholders to define a Microjourney
Testing your application
Troubleshooting tools and techniques

Low-code application development

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 provides data scientists with role-based authoring environment to facilitate
configuration and management of AI and machine-learning resources for predictive, adaptive, and text
analytics. From Prediction Studio, data scientists can also create and explore additional resources that
are related to model development, such as data sets, taxonomies, and sentiment lexicons. Prediction
Studio is available to users who specify pxPredictionStudio as one of the portals associated with their
access group.

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.

Getting started with low-code 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.

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 - frequently asked questions

Exploring application

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.

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.

Exploring application

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.

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

Exploring application

Prediction Studio overview

Prediction Studio provides data scientists with role-based authoring environment to facilitate configuration
and management of AI and machine-learning resources for predictive, adaptive, and text analytics. From
Prediction Studio, data scientists can also create and explore additional resources that are related to model
development, such as data sets, taxonomies, and sentiment lexicons. Prediction Studio is available to users
who specify pxPredictionStudio as one of the portals associated with their access group.

The following components are available in Prediction Studio:

Header
The header at the top enables you to create models, search for the models that you already created,
perform a number of maintenance tasks, or get help.

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

Predictions
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 perform a number of data exploration tasks, such as creating and managing
data sets or viewing 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 and their default application context.

Developer toolbar
This component appears at the bottom of Prediction Studio. From this toolbar, you can access advanced
tools, such as Issues, Tracer, Live UI, Performance, and the Clipboard.

Configuring the JSON data transforms settings column on the Data Transform form

Exploring application
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, contact
your security administrator.

Getting started for development teams

Exploring application

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.

Getting started for development teams

Exploring application

Building your first application

Start developing your projects in a convenient and simplified way by building your first application from a
template. When you create an application, you can save time by reusing default and existing elements.

When you work with Pega Platform, you can quickly create low-code applications in a user-friendly and
intuitive way. 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
Preparing your application for secure deployment.

Start building your application by performing the following tasks:

Creating applications

To start developing your projects in a convenient and intuitive way, build your application on an
application template. When you create an application on a template, you save time because you reuse
key elements of the 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.

Switching between applications in Dev Studio

When you work on multiple applications, you can switch between them by using the Application menu.

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.

Automating work by creating case types

Creating the user experience

Getting started with low-code application development

Creating applications
To start developing your projects in a convenient and intuitive way, build your application on an application
template. When you create an application on a template, you save time because you reuse key elements of
the application, such as case types or data types.

You can choose a default application that Pega Platform provides, or create your 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 people who do not
have an operator ID, configure the Default email account. For more information, see Creating an email
account in Dev Studio.

1. Choose a type of application to create:

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.
To search for an application template, click Search all types.
2. Click Use this application type.
3. If 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 to import.
d. Click Continue.
4. In the Name your application field, enter a unique name for your application.
5. 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.
6. Click Create application.
 7. 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 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 select 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.

8. Click Go to app.

Configuring applications for reuse

Sizing an application development project

Building your first application

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

Building your first application

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.

Keystores
 Building your first 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.

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.

Application types
Creating an application

Building your first application

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

Building your first application

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

Building your first application

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 in Dev Studio.
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.

Presentation Tab

Switching between applications

Switching between applications in Dev Studio

When you work on multiple applications, you can switch between them by using the Application menu.

1. In Dev Studio, click the name of your current application to access the Application menu.
2. Click Switch Application.
3. From the alphabetized list, select an application to become your current application.
Note: The list of available applications is based on the access groups defined on your Operator ID
form. If more than one access group points to the same application, the Switch Application menu
displays the application label followed by the access group in parenthesis.

Building your first application

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.

6. Application Guardrails landing page

7. UI guardrail issues landing page

Compliance score logic

Monitoring project compliance
Viewing application quality metrics

Building your first application

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

Improving your compliance score

Resolving an application warning

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.

Improving your compliance score

Analyzing a compliance score
Justifying an application warning

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

Improving your compliance score

Resolving an application warning
Reviewing user interface components

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

Improving your compliance score

Justifying an application warning
Sharing your compliance score with stakeholders

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.

Improving your compliance score

Reviewing user interface components
Application Guardrails landing page

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.

Sharing your compliance score with stakeholders

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

Sharing your compliance score with stakeholders

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

Improving your compliance score

Sharing your compliance score with stakeholders
Application Guardrails landing page

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

Improving your compliance score

Sharing your compliance score with stakeholders
 Application Guardrails landing page

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, see Security 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. Authentication 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.

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.

If you are running a Pega Platform release prior to 8.4, you should consider customizing the default login
screens to remove references to Pega and the version number.

Restricting access to operator information in public-facing applications

You can restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data
through an access control policy.

Getting started with low-code application development

Restricting access to operator information in public-facing

applications
You can restrict all access to data in the Data-Admin-OperatorID class to only the end user’s data through
an access control policy.

Before you begin: If you are using a version before Pega 8.2, attribute based access control (ABAC) was
disabled by default. To enable this feature, you need to create a dynamic system setting with the value set
to true.

To enable ABAC in any version before Pega 8.2, you need to create a dynamic system setting with the
following attributes:

Short Description: Enable Attribute Based Security

Owning Ruleset: Pega-RulesEngine
Setting purpose: EnableAttributeBasedSecurity
Value: True

1. In the header of Dev Studio, click Create SysAdmin Dynamic System Settings .
2. Create Access Control Policy Condition rule with below details:
Identifier: <Name of your choice>
Ruleset: <Any application ruleset where this restriction needs to be enforced>
Apply To: Data-Admin-Operator-ID
3. On the Pages & Classes tab, add OperatorID in the Page Name field, and Data-Admin-Operator-ID in
the Class field.
4. On the Definition tab, enter the following conditions:
In the Conditional Logic section, name the condition.
In the Policy Conditions section, name the condition the same as the Conditional logic .
In the Column source column, select .pyUserIdentifer.
In the Relationship column, set it to Is equal.
In the Value column, select OperatorID.pyUserIdentifier.
5. Create Access Control Policy rule with below details
Identifier: <Any name of choice>
Action: Read
Ruleset: <Any ruleset in an application where this restriction needs to be enforced>
Apply To: Data-Admin-Operator-ID
6. On the Definition tab, add the name of the Access Control Policy condition rule created in Step 4.

Basic requirements for deploying public-facing applications

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.

Learning about 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

Low-code application development

Learning about 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.

Clusters and operator IDs

After you save a new or updated 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 the rule cache is synchronized, one node might
access a stale copy from its rules cache.

Bulk operator load

You can create operator ID instances by importing a comma-separated values (CSV) file, such as created by
Microsoft Excel. You might need to adapt and extend this example to meet local requirements.

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, an operator ID data
instance is still needed for each user.

Operator passwords
Operator ID passwords are saved as hashed values in the PegaRULES database, using the salted bcrypt
(default) algorithm. Two property types are used 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 it is validated.

On Pega Community, see Using the bcrypt hashing algorithm for Password property types for more
information about the Password property type.

Creating operator IDs

When you create an operator ID in Pega Platform, you set up a unique account so that a user can
access the system. By creating an operator ID you can set the identifying information of the user,
define their access rights, and configure password settings. You can also add additional details, such
as their skills, to ensure that work is routed to the user based on their capabilities.

Defining operator contact information and application access

Define an operator's contact information, application access, and localization information so that
operators can be communicated with and can access the required applications. The access groups
that you specify affect which rulesets, ruleset versions, and portals the operator can access.

Defining operator work groups, work queues, and schedules

Define an operator's skills, work groups, work queues, and work schedule so that work can be
assigned to operators who are skilled and available. The work queues are searched for assignments
when users click Next assignment on the Case Manager portal.

Defining security information for an operator

Use the Security tab to manage operator authentication, passwords, and license type, to allow rule
check out, and to enable and disable the operator.

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.

Understanding Requestor Type data instances

Creating operator IDs
General tab on the Class form
Fields for operator teams, work queues, and schedules
Defining security information for an operator

Understanding project roles and personas

Creating operator IDs

When you create an operator ID in Pega Platform, you set up a unique account so that a user can access
the system. By creating an operator ID you can set the identifying information of the user, define their
access rights, and configure password settings. You can also add additional details, such as their skills, to
ensure that work is routed to the user based on their capabilities.

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 you enter populates the Full name field on the following screen.
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 @ character. Avoid using forward slash (/) or backslash (\) characters in the
identifier.
As a best practice, use the organization name as a suffix in operator IDs.
An operator ID can be up to 65 characters long.
Special processing applies to any user identifier that starts with the word External . Use such
identifiers only to define external operators, those who use directed Web access for one-time
processing of assignments.
Avoid using system as an operator ID name, which is reserved as it refers to agents.
4. Click Create and open . Result: The operator rule form is displayed, where you can continue adding
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 Fields for
operator contact information and application access.
Define organizational information for the operator. For more information, see Fields for operator
teams, work queues, and schedules.
Define a password for the operator. For more information, see Defining security information for an
operator.

Adding an operator by using the organizational chart

Directed Web Access in configuring assignments for external users
Learning about operators

Learning about operators

Defining operator contact information and application access

Define an operator's contact information, application access, and localization information so that operators
can be communicated with and can access the required applications. The access groups that you specify
affect which rulesets, ruleset versions, and portals the operator can access.

Before you begin: Create an operator as described in Creating operator IDs or Adding an operator by
using the organizational chart.

For details about the fields on this screen, see Fields for operator contact information and application
access.

1. On the Profile tab, in the Contact Information section, define personal information for the operator.
Full name is required.
Image
Title
First name
Last name
Full name
Position / job title
Phone
Email
2. On the Profile tab, in the Application Access section, list the access groups that the operator can
choose from at run time. Identify the default access group by clicking the radio button next to the
access group name.
To view the Application Access section, you must have the pxCanManageUsers privilege, which
is included in the PegaRULES:SecurityAdministrator role.
The application for each access group is displayed. To see the roles in an access group, click the
Expand row icon.
3. On the Profile tab, in the Localization section, list the operator's default locale and time zone.
4. Click Save.

General tab on the Class form

 Learning about access groups
Learning about operators

Learning about operators

Defining operator work groups, work queues, and schedules

Define an operator's skills, work groups, work queues, and work schedule so that work can be assigned to
operators who are skilled and available. The work queues are searched for assignments when users click
Next assignment on the Case Manager portal.

Before you begin: Create an operator as described in Creating operator IDs or Adding an operator by
using the organizational chart.

For details about the fields on this screen, see Fields for operator teams, work queues, and schedules.

1. On the Work tab, in the Routing section, identify properties of the operator that relate to the
assignment of work, including: organization, skill, work queue, and whether the operator is able to
receive work assignments. Identify the default work group by clicking the radio button next to the
work group name.
Organization, division, and unit
One or more work groups, with one identified as default
Reports to operator
Skills with associated ratings
Work queues with associated urgency thresholds
Get from work queues first check box
Use all work queue assignments in user's workgroup check box
Merge work queues check box
2. On the Work tab, in the Availability section, identify properties that relate to the operator's work
schedule.
Operator is available to receive work check box
Business calendar name
Dates of scheduled absences
How to assign work when operator is absent (operator or work queue, decision tree to find
substitute, and default assignee)
3. Click Save.

Fields for operator teams, work queues, and schedules

Initial Work queues (Data-Admin-WorkBasket)
Adding a secondary manager to a team
Learning about operators

Learning about operators

Defining security information for an operator

Use the Security tab to manage operator authentication, passwords, and license type, to allow rule check
out, and to enable and disable the operator.

Note: The Unattended operator (robot) check box is selected if this operator is a robotic automation
virtual machine (VM). Unattended operators are generated for each registered VM in a robotic process
automation (RPA) solution.

1. To change an operator's password, click Update password.

a. In the Change Operator ID Password dialog box, in the New Password field, enter the new
password.
b. In the Confirm New Password field, reenter the password to confirm it.
c. Click Submit.

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

You can set the password policy from Configure System Settings Security Policies .
 As a security feature, the passwords for administrator@pega.com and three other initial operator IDs
can be changed only by logging in as one of those operators.

2. Optional: To allow this operator to update rules in rulesets that use rule checkout, select the Allow
rule check out check box.
3. Optional: To authenticate this operator only through external authentication facilities, select the Use
external authentication check box.
4. Optional: To force the operator to change their password next time the operator logs in, select the
Force password change on next login check box.
5. Optional: To disable the operator, select the Disable Operator check box.
Note: If the operator is provided with Pega Platform, enter a new password that is consistent with
your security policies. Change the password by clicking Update Password and send the new
password to the enabled operator.
6. Optional: In the Starting activity to execute field, specify the first activity that the system runs
after this user is authenticated. The default is Data-Portal.ShowDesktop.
7. In the License type list, click the license type.
Named – Human users who do business operations by using a Pega application or customer-
created interface
Invocation – Abstract users that are used for agents, services, and other background processes,
and external users whose processing is typically done through the Directed Web Access feature

Learning about operators

Configuring robotic process automation
Robotic process automation
License compliance
Checking out a rule

Learning about operators

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 Setting your work availability.

Learning about operators

Learning about 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.

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.

Managing access roles

General tab on the Class form
Understanding Requestor Type data instances

Understanding project roles and personas

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 .

Learning about operators

General tab on the Class form

Learning about access groups

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 the PegaRULES: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

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

Learning about access groups

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

Assigning work pools 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.

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.

Keystores
Changing your workspace
Adding a role to an access group
Learning about access groups

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 the Pega
Community article 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

Learning about access groups

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

Configuring tools access

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

Configuring tools access

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

Configuring tools access

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.

Keystores
Changing your workspace
Adding a role to an access group
Learning about access groups

Learning about 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.

You can also refer to teams as work groups.

1. In
the header of App Studio, navigate to a portal that contains the My Teams widget.
2. In
the navigation pane, click My 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. 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.

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.

Inviting collaborators to your application

Removing a team member

Understanding project roles and personas

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

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

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.

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

2. 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.

Removing a team member

Creating a team

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: 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, navigate to a portal that contains the My Teams widget.
2. In
the navigation pane, click My Teams.
3. In
the My Teams section, click the name of the team that you want to edit.
4. In
the Work queues section, click Add new.
5. 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.
6. Optional: To add more work queues, repeat steps 4 and 5.

Collaborating on cases

Creating a team

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.

Understanding project roles and personas

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.

Configuring default feed sources

Ensure that users see only relevant Pulse posts by filtering feed sources that display Pulse messages
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

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 are involved, or posts a
comment on a case that you are following, provided that your application is configured to send emails.

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

Collaborating on cases

Adding the Pulse gadget to your application

Applicable to Theme UI-Kit applications

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

Collaborating with users by using Pulse

Enabling users to post messages in the activity feed

Applicable to Theme UI-Kit applications

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 feed sources for activity feeds

Adding the Pulse gadget to your application
Presentation Tab

Collaborating with users by using Pulse

Creating feed sources for activity feeds

Applicable to Theme UI-Kit applications

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 messages between team or department members.
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.

Enabling users to post messages in the activity feed

Adding the Pulse gadget to your application
Presentation Tab

Collaborating with users by using Pulse

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
 Collaborating with users by using Pulse

Configuring default feed sources

Applicable to Theme UI-Kit applications

Ensure that users see only relevant Pulse posts by filtering feed sources that display Pulse messages 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

Collaborating with users by using Pulse

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. 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

Collaborating with users by using 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

Collaborating with users by using 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 Memebers 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

Collaborating with users by using Pulse

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

Collaborating with users by using 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

Collaborating with users by using Pulse

Configuring Pulse email notifications

Applicable to Theme UI-Kit applications

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 are involved, or posts a comment on a case
that you are following, provided that your application is configured to send emails.

Before you begin: Set your notification preferences.

In addition to receiving email notifications, you can continue a Pulse discussion that was initiated by email.
When you reply to a message that is denoted by the Email icon, your post and attachment, if any, are
added to Pulse and sent to the relevant user in an email message.

The following tasks can help you configure email notifications for Pulse:

Configuring an email account for Pulse notifications

Enabling users to respond to Pulse email notifications
Configuring Pulse notifications on additional email accounts

Configuring an email account for Pulse notifications

In Pulse, users can choose to receive email notifications when posts are made on cases that they are
following. They also receive emails when other users reference them in posts, like their posts, and so
on.

Enabling users to respond to Pulse email notifications

Users can receive Pulse emails on cases that they are following and for which they choose to receive
notifications. Users also receive emails when other users reference them in 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.

Configuring Pulse notifications on additional email accounts

After you create the PulseNotifications email account that is used to send Pulse notifications, you can
configure individual email accounts for each application for which you want to send Pulse notifications.

Collaborating with users by using Pulse

Configuring an email account for Pulse notifications

Applicable to Theme UI-Kit applications

In Pulse, users can choose to receive email notifications when posts are made on cases that they are
following. They also receive emails when other users reference them in posts, like their posts, and so on.

Create an email account from which to send notifications by completing the following steps.

1. Select Create Integration Resources Email Account .

2. Enter PulseNotifications in the Account Name field. You can have only one account named
PulseNotifications in the system.
3. Click Create and open .
4. Configure the email account, as appropriate.
5. Allow users to reply to email notifications with text or attachments and post the reply as a response to
the original message. See Enabling users to respond to Pulse email notifications.
6. Configure additional email accounts for each application for which you want to send Pulse notifications.
See Configuring Pulse notifications on additional email accounts.

Configuring Pulse email notifications

Integrating with an email provider

Configuring Pulse email notifications

Enabling users to respond to Pulse email notifications

Applicable to Theme UI-Kit applications

Users can receive Pulse emails on cases that they are following and for which they choose to receive
notifications. Users also receive emails when other users reference them in 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.

For example, in a sales automation scenario, a Pulse discussion about converting a prospect to a customer
is occurring on a case. A sales executive can quickly add comments to a post and attach a related
document by replying to an email without 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.

1. Ensure that you have configured an email account from which to send notifications:
If you have not configured an email account, create the PulseNotifications account. See
Configuring an email account for Pulse notifications.
By default, the system looks for the email account with the name PulseNotifications to process
emails. All applications in the system use this account to process emails. If you want to configure
a different email account for your application, see Configuring Pulse notifications on additional
email accounts.
2. Create a service package in the application ruleset:
a. Click Create Integration Resources Service Package .
b. Enter a short description and name for the service package.
c. Click Create and open .
d. In the Service access group field, enter the access group of your application. Ensure that this
access group is configured to access service methods.
e. Clear the Requires authentication check box to bypass authentication and allow the Pega
Platform to invoke service methods.
f. Select Suppress Show-HTML.
g. Click Save.
3. 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. Enter a name for the rule in the Label field.
f. In the Customer Package Name field, enter the name of the service package that you created
 in step 2.
g. Enter a service class name in the Customer Class Name field.
h. Select your application ruleset from the Add to ruleset list.
i. Click Create and open .
j. In the Primary Page section of the Service tab, ensure that PegaSocial-Message is entered in
the Primary page class field.
k. In the Service activity section, ensure that pzPostReplyFromMail is entered in the Activity
name field.
l. On the Request tab, ensure that the Message header and Message data sections are
populated with the same values as the values for the pzCreatePulseReply service email rule.
m. On the Response tab, ensure that None is selected from the Message type list to avoid
receiving blank emails when users reply to Pulse emails.
n. Click Save.
4. Create an email listener rule.
a. Select Create Integration Resources Email Listener .
b. Enter a short description and listener name.
c. Click Create and open .
d. On the Properties tab, from the Startup option list, select the appropriate option for running
the listener, depending on your requirements. If you select Node based startup, you can find
the node ID on the clipboard by clicking System Pages pxProcess and viewing the
pxSystemNodeID.
e. In the Email Account field, enter the email account for the listener. You can use the same
account that you used for sending emails.
f. In the Service information section, in the Service package field, enter the service package
that you created in step 2.
g. 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.
h. In the Service method field, enter the name of the service email that you created in step 3.
i. On the Processes tab, ensure that the No Attachments check box is cleared so that
attachments can be sent to email replies.
j. Click Save.
5. Use Admin Studio to start the email listener. For more information, see Managing listeners and the
help.

Configuring Pulse email notifications

Creating a Service Email rule
Creating an email listener
Managing listeners

Configuring Pulse email notifications

Configuring Pulse notifications on additional email accounts

Applicable to Theme UI-Kit applications

After you create the PulseNotifications email account that is used to send Pulse notifications, you can
configure individual email accounts for each application for which you want to send Pulse notifications.

For example, you can configure an email account, such as HRServices@example.com, to send Pulse emails
from the HR Services application. You can also configure an email account, such as
SalesAutomation@example.com to send Pulse emails from the Sales Automation application, and so on.

1. Create an email account for your application by clicking Create Integration Resources Email
Account .
2. Save the pyPulseNotificationsEmailAccount data transform, contained in the Pega-Social ruleset, to
your application ruleset.
3. Set the Param.PulseNotificationsEmailAccount to your email account name.
4. Click Save.
5. Allow users to reply to email notifications with text or attachments and post the reply as a response to
the original message.

Configuring an email account for Pulse notifications

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

Configuring Pulse email notifications

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

Collaborating with users by using Pulse

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

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

Enhancing a message in Pulse

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

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.

Differentiating case references in Pulse

Restricting case references in Pulse

Enhancing a message in Pulse

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
Report Definition Query tab
Finding rules by class

Adding a reference in Pulse

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

Adding a reference in Pulse

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

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

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

Collaborating with users by using 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.

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

Managing Pulse messages

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

Managing Pulse messages

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

Managing Pulse messages

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

Managing Pulse messages

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

Managing Pulse messages

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

Managing Pulse messages

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 Pulse

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.

Collaborating with users by using Pulse

Collaborating on cases

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

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

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

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.

Managing pins
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

Collaborating with users by using spaces

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

Pinning content to a space

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

Pinning content to a 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.

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

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 a 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.

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

Managing a 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.

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

Managing a space

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

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

Adding 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

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 panel of the portal that you use, for example App Studio, 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

Collaborating with users by using spaces

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

Collaborating with users by using spaces

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.

Referencing a document from a case

Collaborating on cases

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

Collaborating on shared content by using documents

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
Referencing a document from a case

Collaborating on shared content by using documents

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 development of your application, manage the workload in your team, and prioritize your work
accordingly by following the application backlog on your Inventory page. The Inventory landing page
lists 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 - frequently asked questions

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

Low-code application development

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 About the 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.

Adding case types to organize work

Adding personas to organize users
Adding data objects to organize data
Data modeling
Creating a model for your data

Creating a Microjourney for customer success

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 Creating a case type.

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 Microjourney for customer success

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.

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.

Creating a case type

Defining the case life cycle
Creating a Microjourney for customer success

Adding case types to organize work

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 Adding a process to a stage.

Defining the case life cycle

Creating an alternate stage
Adding a process to a stage

Adding case types to organize work

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.

Conditionally starting a process

Adding case types to organize work

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 a preconfigured step to a process

Adding case types to organize work

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.

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.

Understanding project roles and personas

Creating a Microjourney for customer success

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

Learning about operators
Learning about access groups
Creating a team

Adding personas to organize users

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 Creating a case type.

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.

You can associate a persona with multiple stages of your case life cycle, as well as with multiple releases of
your application. For example, in a hiring process, you can associate a job candidate with Collect personal
details and Inform about decision stages. In the first release of your application, in the Collect personal
details stage, the candidate can provide personal details in a questionnaire. In the second release, the
candidate can also upload required documents.

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
In the personas list, select a persona that you want to add.
persona
3. In the Persona properties panel, in the Channel list, select the channels that the persona can access.
4. Optional: To plan when you want to include the persona in your Microjourney, associate the persona
with a release:
a. In the Additional details section, click Configure release.
b. In the Edit details window, in the Release list, select the release.
c. Optional: To provide more information, in the Comment text box, enter a short description.
d. When you implement the persona, select the Mark as done check box.
e. Click OK.
 5. Click Save.

Result: Your case life cycle displays the personas that you can use when you plan your application
development.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.

Understanding project roles and personas

Adding personas to organize users

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

Adding personas to organize users

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 indicate 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.

Creating a Microjourney for customer success

Associating data objects with case types

Provide the transparency of data that a Microjourney requires by associating data objects with case types.
When you indicate 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 Personal details and Contact details data objects 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 section of a stage in which you want to add a data object, click Add data object, and
then select a data object that you want to use:
Choices Actions

a. In the data objects list, select Create new.

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 data objects list, select the data object that you want to add.
data object
3. In the Data object properties panel, in the System list, select a system that you want to associate
with the data object:
Choices Actions

a. In the list, select Create new.

Create a new
b. In the New system window, in the Name field, enter a descriptive name for
system
the system. For example: Enter LinkedIn.

Select an
In the list, select the system that you want to use.
existing system
4. Optional: To enable reading of the data object from the system, select the Read check box.
5. Optional: To enable updating of the data object in the system, select the Update check box.
6. 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 window, in the Release list, select the release.
c. Optional: To provide more information, in the Comment text box, enter a short description.
d. When you implement the data object, select the Mark as done check box.
e. Click OK.
7. 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.
 Data modeling
Creating a model for your data
Integration systems

Adding data objects to organize data

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
Creating a model for your data

Adding data objects to organize data

Managing application inventory

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

By analyzing the 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. Because of
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.

Before you begin:

Create a case type, and then define the case life cycle by adding stages, processes, and steps. See
 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 information that your cases require to reach the resolution. See
Adding data objects to organize data.

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 type of information that you want to view:
To manage draft personas, select Personas.
To manage draft data objects, select Data.
4. Manage the list of items to display information that you need:
To group personas or data objects, click Group, and then in the list, select the grouping method
that you want to apply, for example Case types.
To display only selected information about personas or data objects, 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 personas or data objects 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 release in which you want to implement the persona or data object, in the
Release list, select a release.
To provide more information about a persona or data object, in the Comment text box, enter an
additional description.
To mark the persona or data object as implemented, select the Mark as done check box.
6. Click Submit.

Creating a team
Configuring your dashboard

Creating a Microjourney for customer success

The Microjourney in the Pega Express methodology - frequently

asked questions
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.

Adding case types to organize work

Adding personas to organize users
Adding data objects to organize data
Data modeling
Creating a model for your data

Creating a Microjourney for customer success

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.

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 the search algorithm that the system uses to find the best or most appropriate rule
instance to apply in a situation.

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.

Finding deprecated rules in sections

Find sections that use deprecated rules by using an application upgrade utility. Once found, these
legacy rules can be updated to newer rules.

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.

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.

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.

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.

Managing relevant records and components

Save time during application development by reusing elements such as relevant records and
components.

Calculating values and making decisions

To provide automated solutions for your application users, define automatic was of making decisions
and calculating values in your business processes.

Calculating or validating values automatically

To save time and reduce the risk of errors during calculation, provide tools for your application that
calculate and validate values in an automatic way.

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 in a form of a rule stores a
graphics file, such as an image, or other non-text files. Binary file rule type provides the security,
inheritance versioning, and deployment benefits of rule resolution to a file.

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.

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

You run a preflight optimization to reduce an application’s unnecessary static content and improve its
loading time.

Troubleshooting tools and techniques

Low-code application development

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 Defining the case life cycle.

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.

Naming conventions for specific records

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

Constraints rules -
Declare Expression rules - Completing the New or Save As form
Creating a privilege
Creating a When rule
Creating rulesets
Naming conventions for classes
Naming conventions for properties
Creating an activity
Case status values
Configuring data transform
Creating operator IDs
Creating a case type
Adding a stage to a case life cycle
Adding a process to a stage
Adding a step to a process

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.

Organizing rules into rulesets

Organizing rules into classes

Designing applications for reuse and extension

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 .

Setting rule status and availability

Searching for a rule
Configuring system settings

Designing applications for reuse and extension

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 realize
that you want to capture multiple phone numbers. Instead, 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.

Designing applications for reuse and extension

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.

About the Ruleset Maintenance wizard

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

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

Organizing rules

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 version

Create a new version of an existing ruleset or create a new ruleset with an associated ruleset version.

Completing the Save As RuleSet form

You can use the Save As RuleSet form to copy a ruleset. The system copies the values in the Security,
Category, and History tabs. The version is the one you specify in this form.

Creating branch rulesets

You create branch rulesets in the Branch area on the Application rule's Definition tab. When branching
a ruleset, the non-branch ruleset's Validation mode is used by the branch.

Keystores
Keystores
Keystores
Learning about operators

Organizing rules into rulesets

Creating a ruleset version

Create a new version of an existing ruleset or create a new ruleset with an associated ruleset version.

1. In the navigation panel, click Records SysAdmin RuleSet .

2. On the Ruleset instances page, click Create.
3. On the Create RuleSet Version page, in the RuleSet Name field, enter a name starting with a
letter, or press the Down arrow key to select an existing ruleset. Result: When you enter a new
ruleset name, the system enters a default three-part version identifier of 01-01-01 in the Version
field, and a unique two-part short description comprising the name and the default version in the
Description field.

For more information, see Configuring ruleset version settings.

4. Optional: To...select Branch RuleSet.

a. In the Branch ID field, select
b. In the Ruleset to branch field, select
5. Optional: To add this ruleset version to the top of the Application Ruleset list in the current
application rule, select Update my current Application to include the new version (Quick
Create Only).
a. Click Create and close. Result: The system saves the ruleset and version without opening the
ruleset form.
6. Click Create and open .
7. On the Versions tab, in the Validation mode section, select a validation mode.
Application Validation
Ruleset Validation
The system displays the following fields:
Secure – Identifies a locked or unlocked ruleset version.
Effective Start Date – Displays the date on which the rule was created.
View History – View the history of the ruleset version, such as the time it was last updated.
Required Rulesets and Versions – This option appears when you select Ruleset Validation.
Enter one or more ruleset versions that the ruleset version requires as a prerequisite.
Version – Displays the ruleset version.
Description – Displays the description that the system generated when you entered a ruleset
name on the Create RuleSet Version page. Keep the default description or modify it.
Approval required – Select this option to require a development approval workflow, identified in
 the RuleSet Name rule, for checking in rules for this version of this ruleset.
Checked out – Displays the number of rule instances that use this version that are currently
checked out. To view the number of rule instances grouped by rule type, click the number that is
displayed in this column.
All rules – Displays the number of rule instances using this version. To view a summary report of
the number of rules by rule type, click the number that is displayed in this column.
8. Optional: To lock a version, in the Secure column, expand the row and complete the following steps:
a. Click Lock and Save.
b. In the Lock Ruleset Version window, enter a password and click Submit.
9. Optional: To unlock a version, in the Secure column, expand the row and complete the following
steps:
a. Click Unlock and Save .
b. In the Unlock Ruleset Version window, enter a password and click Submit.
10. Click Save.

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 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
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

Creating a ruleset version

Completing the Save As RuleSet form

You can use the Save As RuleSet form to copy a ruleset. The system copies the values in the Security,
Category, and History tabs. The version is the one you specify in this form.

Note: You cannot use this form to add a version to a ruleset. To add a version, open the Create Ruleset
Version form as described in Creating a ruleset version, select an existing ruleset, and update the Version
field. Alternatively, open the Versions tab on the ruleset form, add a row in the Versions array, and
complete the Create Ruleset Version form. See Using the Versions tab..

1. Open the ruleset and open the Save As RuleSet form.

2. Enter a new, unique ruleset name.
Do not select an existing name from SmartPrompt. You cannot add a version to an existing ruleset on
this form.
3. Keep the default version (01-01-01) or modify it.
4. Keep the default Description value or modify it.
5. Update the prerequisite RuleSets and versions if necessary.
6. Optional: Select the Update my current Application to include the new version check box.
7. Save the copied ruleset:
If you want to use the ruleset form, click Create.
If you want to automatically save the ruleset and version without opening the ruleset form, click
Quick Create.
8. Save the ruleset to save the ruleset and version.

Creating rulesets

Creating branch rulesets

You create branch rulesets in the Branch area on the Application rule's Definition tab. When branching
a ruleset, the non-branch ruleset's Validation mode is used by the branch.

Creating branches

Creating rulesets

About the Ruleset Maintenance wizard

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

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

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

Moving a ruleset
To move a ruleset, select an existing ruleset and specify a target name and, optionally, a version. The
wizard processes the source rules in each ruleset version in the ruleset and any non-versioned rules
associated with the ruleset. The RuleSet and RuleSet Version fields of each rule are updated to the
values specified as the target. The result is that the rule appears to have been deleted from its source
ruleset and copied into the target ruleset. The value of the rule's pzInsKey does not change.

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

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

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

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

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

You cannot copy a ruleset.

Copying or moving a ruleset version

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

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

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

Merging rulesets and ruleset versions

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

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

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

Note: Compress rulesets with prerequisites beginning with the ruleset of least dependency. For example, if
ruleset A requires ruleset B as a prerequisite, and ruleset B requires ruleset C as a prerequisite, then you
should compress the ruleset A first, then B, and finally C. If you compress the rulesets in the order C, B, and
A, you risk losing some rules that you expected to retain.
When you merge rulesets or ruleset versions, you have the option of deleting the sources once the merge is
complete. However, if you merge ruleset versions and opt to delete the sources, the source versions are
deleted, but not their ruleset(s).

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

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

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

Changing a ruleset version number

You can change the version number for a particular ruleset version, whether or not the version which you
designate as the new number already exists. The target version belongs to the same ruleset as the source
version. All rules, including non-resolved rules, from the source ruleset version become part of the target
version. All rules retain their original pzInsKey values, and therefore retain their History.

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

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

Locked ruleset versions

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

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

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

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

Affected rules and data instances

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

Ruleset versions ( “prerequisite” field)

Rule-Application (lists on the General tab)
Organization data instance (listing ruleset versions here is possible, deprecated)
Access group data instances
Prerequisites and preparation
Before running the RuleSet Maintenance wizard, consider the following guidelines:

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

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

Starting the wizard

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

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

Recommended next steps

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

If a ruleset to be moved is referenced in an application rule, be sure to update the references on the
application rule form:

- Application RuleSets section on the General tab

- Component and Shared RuleSets section on the General tab

- Production RuleSets section on the General tab

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

Recovering merged rulesets

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

Logging
Each execution of this wizard creates an instance of the Log-Merge-RuleSet class, including error messages
or other results. The key to this instance is the date and time the wizard was started.

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

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

RuleSet Maintenance wizard step 1

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

RuleSet Maintenance wizard step 2

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

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.

Organizing rules into rulesets

RuleSet Maintenance wizard step 1

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

Preparation and prerequisites

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

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

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

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

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

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

Completing the form

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

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

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

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

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

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

4. Adjust order of precedence, if needed.

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

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

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

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

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

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

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

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

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

7. For Merge, specify whether the source rulesets or ruleset versions are to be deleted after the merge is
complete. Select Yes to delete the sources; No to retain them. If you are merging ruleset versions and
opt to delete the source versions, their parent rulesets are not deleted.

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

Note: When you select Libraries and Functions from the list of non-versioned rules, all functions are
merged when the ruleset name has changed. When the ruleset name is the same and only the version
has changed, functions are treated like versioned rules.
9. Click Next to continue to the next form in the wizard. See RuleSet Maintenance wizard 2. Click Cancel
and then click Done to cancel the wizard.

About the RuleSet Maintenance wizard

About the Ruleset Maintenance wizard

RuleSet Maintenance wizard step 2

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

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

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

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

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

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

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

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

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

Click Cancel and then click Done to cancel the wizard.

About the RuleSet Maintenance wizard

About the Ruleset Maintenance wizard

RuleSet Maintenance wizard step 3

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

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

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

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

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
Application Development landing page
Organizing rules into rulesets

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

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.

About the Ruleset Maintenance wizard

Distributing applications between systems
Organizing rules into rulesets

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.

Class layers

Classes define the applicability, or scope, of a rule instance. Knowledge of the different layers of
classes and their inheritance relationships 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.

External classes

An external class is a concrete class (instance of the Rule-Obj-Class rule type) that corresponds to a
table in an external relational database, rather than to a table or view in the PegaRULES database.

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
Connector and Metadata wizard or the Database Class Mapping 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

Organizing rules

Class layers
Classes define the applicability, or scope, of a rule instance. Knowledge of the different layers of classes
and their inheritance relationships 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 organization unit. Framework classes belong to
the framework layer.

For example, the MyCo enterprise makes auto loans and has an auto loan framework application that
contains all of the assets needed for the basic auto loan process. Then, the MyCo enterprise develops two
implementations 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 a framework application. You can reuse some or all of the case types and data types of the
framework. From the 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 extend the framework so that it is used by other implementations that
you might create later. As a best practice, reuse framework rules and create only specialized rules in your
implementation application. For example, use report definitions in the framework classes that run with the
corresponding implementation classes.

Note: Framework classes are different from Strategic Applications, which are starter applications for
specific industries or lines of business.

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 organization 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 must be reused for business logic.
Data assets include classes and rules for data stored in the system, and classes and rules for access to data
in external systems by using connectors. Business logic assets include standard properties, decision tables,
and service-level agreements.

For example, the MyCo enterprise might want to reuse, on an enterprise-wide basis, the property for
employee serial number. By reusing this property, the various applications across the enterprise that an
employee uses can consistently rely on the same serial number property for 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.

Note: To identify the inheritance relationships among these classes, you can right-click the class name in
the Application Explorer and select the Inheritance option.

Configuring applications for reuse

Creating applications
Creating an application

Organizing rules into classes

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.

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

Organizing rules into classes

External classes
An external class is a concrete class (instance of the Rule-Obj-Class rule type) that corresponds to a table in
an external relational database, rather than to a table or view in the PegaRULES database.

You can create an external class and associated properties by using one of the following tools:

The Connector and Metadata wizard

The New External Database Table Class Mapping button on the Data Model: Classes and Properties
landing page

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 instance ( Data-Admin-DB-Table class), 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,
Declare Expression rules (Rule-Declare-Expressions rule type), validate rules ( Rule-Obj-Validate rule type),
and trigger rules ( Rule-Declare-Trigger rule type) do operate on clipboard property values for external
classes.

External classes do not contain the properties @baseclass.pzInsKey and @baseclass.pxObjClass, 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, the performance of database insert, delete, and update operations for external classes can
be improved 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.

Commit method

Organizing rules into classes

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.
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.
For more information 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 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 version
Creating branch rulesets
Deleting a rule

Organizing rules into classes

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
Class layers
Creating classes

Creating classes

Class keys
When you define concrete classes, you can add keys to identify 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 properties that 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 may 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, in what order, to connect 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 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 the system finds
such a class, it connects 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, 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 first save the Class form. If you want to use one or
more properties already defined to apply to a super class of this class as key properties, enter them
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 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. 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 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

Creating classes

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.

 Field Description
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.

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

This check box appears only for concrete classes. It affects only instances of exactly 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.

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

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.
 Field Typically, the key of an object also determines how it is identified when locked. In the
Description
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.

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
Field all rule types with an Applies To key part.
Description
(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

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.

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 check-out (by updating the
RuleSet to allow checkout, and updating the Operator ID to enable checkout), not locks.

If this class is part of a class group, the Lock field on the class group form supersedes this
Allow
Allow Locking? value.
Locking
If selected, a user cannot save or delete an instance within the scope of this class group unless
that user holds a lock on the object. Typically, activities acquire locks when they open an
instance to the clipboard.

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

Organizing rules into classes

Organizing rules into classes

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
Java Beans 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. This
information is found on the Versions tab of the ruleset name form.

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

Organizing rules into classes

External Mapping tab on the Class form

The External Mapping tab is used primarily for external classes. External classes are created by the
Connector and Metadata wizard or the Database Class Mapping 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

Organizing rules into classes

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.
 Selecting a Class to Rename and RuleSets

Use the Rename a Class wizard to select class to rename and rulesets.

Verifying classes

Verify the classes to rename with the Rename a Class wizard.

Identifying locked ruleset versions

To avoid errors with the Rename a Class wizard, identify rules in locked ruleset versions.

Checking for checked-out rules

To avoid errors, review the list of checked-out rules before you continue to use the Renaming Class
wizard.

Reviewing the list of rules to change

This form reports the number of occurrences of the class or ruleset names that to change.

Selecting additional rules to change

Use the Rename Class wizard additional rules report to list matches with the class name you asked to
change that are found in strings that are not clearly class names. These are additional occurrences not
included in the summary on the page, "Rules That Will Be Changed." The wizard cannot determine
whether these strings should be changed when the class names are changed.

Reviewing the results

Review the list of rule instances that you selected to be renamed that could not be changed
successfully. Hover over the error message in the Status column to see more details on the error.

Using the Rename a Class wizard

Work Objects

Understanding class hierarchy and inheritance

Purging and archiving old work items

Organizing rules into classes

Selecting a Class to Rename and RuleSets

Use the Rename a Class wizard to select class to rename and rulesets.

Use this form to specify the class you want to rename and the options for the procedure.

Complete the fields as follows:

Field Description

The name of the class to be renamed.

Old Class Name The search for this class name is not case-sensitive. The wizard matches all
occurrences of this string in the system, regardless of case.

New Class
The new name to be applied to the class.
Name

Select Yes to present a list of rulesets in your ruleset list (excluding the standard Pega-
rulesets, which define PRPC; all versions of these rulesets are locked) in the Select
Limit search to Ruleset Scope box. Select one or more rulesets.
RuleSets in my
Select No to present list of all rulesets in the system (excluding the standard Pega-
RuleSet List
rulesets, which define PRPC; all versions of these rulesets are locked.) in the Select
 Field Ruleset Scope box. SelectDescription
one or more rulesets in the system.

Within this box appear the rulesets that may be searched during the renaming
Select RuleSet
process. Select each one that you want to include in the search for references to the
Scope
class you are renaming.

Next >> Click to continue to the next step of the wizard.

Cancel Click to exit the wizard.

Step 2

About the Rename a Class wizard

About the Rename a Class wizard

Verifying classes
Verify the classes to rename with the Rename a Class wizard.

This page lists all the classes that will be renamed, including the subclasses of the class you specified that
are associated by pattern inheritance with the original name. The page displays the number of records
searched, the number of records in which the class name occurred, and the total number of occurrences.

The page displays the old name, new name, and ruleset of each class that will be changed. The matching
substring that will be changed within each class name is highlighted in red.

This form has no input fields. To confirm these changes, click Next >> to continue to the next form of the
wizard.

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

About the Rename a Class wizard

About the Rename a Class wizard

Identifying locked ruleset versions

To avoid errors with the Rename a Class wizard, identify rules in locked ruleset versions.

If the wizard finds rules to be modified in locked rulesets or locked ruleset Versions, this form displays a list
of the locked rulesets and ruleset versions. You can Click Export to Excel to save this listing in a
spreadsheet. For each ruleset version, supply a password to unlock the ruleset or check Skip.

If you provide a password, the wizard unlocks the ruleset version, renames the rules as specified, and
then relocks the ruleset.
If you choose Skip, the wizard will not rename rules in the ruleset. These rules will be listed on the
wizard summary page with a status of SKIPPED.

click Next >> to continue to the next form of the wizard.

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

About the Rename a Class wizard

About the Rename a Class wizard

Checking for checked-out rules

To avoid errors, review the list of checked-out rules before you continue to use the Renaming Class wizard.

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.

Use the report window to review the checked out rule. Check in any rules you have checked out and
arrange for any rules in the report that are checked out by other users to be checked in.

When all rules are checked in, click Next>> to continue.

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

Note:

You can continue the rename process with checked out rules. The wizard will rename the original rule, but
checked out instances of the rule will not be modified. As a result, the checked out instances will no longer
be able to be checked in and changes to the checked out instances will be lost.

If you exit the wizard to arrange for rules to be checked in, resume the renaming process by restarting the
wizard from the beginning.

About the Rename a Class wizard

About the Rename a Class wizard

Reviewing the list of rules to change

This form reports the number of occurrences of the class or ruleset names that to change.

If you want to review all the rules that will be changed, click Export To Excel to create an Excel
spreadsheet containing a detailed listing of the rules that will be changed.

Click Next to confirm the changes.

About the Rename a Class wizard

About the Rename a Class wizard

Selecting additional rules to change

Use the Rename Class wizard additional rules report to list matches with the class name you asked to
change that are found in strings that are not clearly class names. These are additional occurrences not
included in the summary on the page, "Rules That Will Be Changed." The wizard cannot determine whether
these strings should be changed when the class names are changed.

For example, if the original class name is your company name, you may have also used that string in other
properties in the system that you do not want to change.

Use the navigation tools at the top-right of the form to page through the listing and review the Value
column to see the string that will be changed. Select the check box next to each instance that you want to
rename, or select the check box at the top of the Rule Type column to select all the instances on this page.
You must display each page and select the instances that you want to include. Only selected instances will
be renamed.

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.

When you are satisfied with the selection, click Next to begin the renaming.

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

About the Rename a Class wizard

About the Rename a Class wizard

Reviewing the results

Review the list of rule instances that you selected to be renamed that could not be changed successfully.
Hover over the error message in the Status column to see more details on the error.

The Status column reports the following error conditions:

 FAIL – The system was unable to refactor the rule.
SKIPPED – The rule was not selected for refactoring on the previous page of the wizard.

REFACTORED WITH ERRORS – The refactored rule was saved to the system, but the rule is not valid. Review
these rules in the Pega Platform and correct the validation errors.

Click Export All To Excel to get a complete listing of the results for all the rules, both successful and
unsuccessful.

Click Finish to exit from the wizard.

Note: If you delegate a rule or data type and then rename the class, you must re-delegate the class.

About the Rename a Class wizard

About the Rename a Class wizard

Using the Rename a Class wizard

Work Objects

This page appears only if there are work item instances associated with any of the classes that will be
renamed.

In the Rename field, click Yes to update the work item instances by changing the pxInsName and pzInsKey
values to reference the new class name, or click No to leave the work items unchanged.

If you choose No, after the rename process is complete, work items that referenced the original class can
only be viewed as XML.

Click Next >> to continue to the next step of the wizard.

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

About the Rename a Class wizard

About the Rename a Class wizard

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 —

Organizing rules into classes

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

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

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

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

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

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 realize that
you want to capture multiple phone numbers. Instead, 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 (makes invisible to rule resolution) a
rule 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 associated with your access role allows you to delete rules or data
instances.

– If no Access Deny rules associated with your access role disallow you to delete rules or data
instances.

You cannot delete a rule where 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 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 that 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.

Restrictions on deleting rules

The following conditions can prevent you from deleting a 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

Organizing rules

Restrictions on deleting 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—makes invisible to rule resolution—
a rule no longer useful or wanted in your application.
By definition, you cannot delete standard rules, because they are part of the Pega Platform product.
Many can be overridden, but none can be deleted.
You cannot delete any rule or data instance unless allowed by an Access of Role to Object rule
associated with your access role, and also not disallowed by any Access Deny rules associated with
your access role.
You cannot delete a rule where 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 when the operator checked-out rules. Have the operator 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, when the system contains rules with that class
name as the Applies To class. You are prompted with a list of the rules that you must delete before the
class rule itself is deleted.
You cannot delete a ruleset version rule that identifies a non-empty collection of rules. Delete each of
the rules in the version first.
You cannot delete a ruleset for which a ruleset version exists. Delete each version first.

Deleting a rule

Deleting a 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.

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

Deleting a rule

Rule resolution
Rule resolution is the search algorithm that the system uses to find the best or most appropriate rule
instance to apply in a situation.

Rule resolution applies to all but a few rule types — classes that inherit from the Rule- class. Rule resolution
does not apply to instances of classes derived from the Work-, Data-, or any other base class.

While the rule resolution algorithm is fast and invisible, it is important to understand how it operates. As
you create applications, make your choices of values for key parts based on how you want rules to be found
by rule resolution.

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, it accepts what is in the cache as the candidate rules and
skips many steps in the resolution process (see below).
The benefits of rule resolution include:

Rules can be shared across applications and organizations. Sharing and reuse are major benefits of
object oriented software development.
Rules defined at a higher level can be overridden by more specific rules defined at a lower level. While
this dilutes the sharing benefit, it provides often needed flexibility while bringing visibility to
exceptions.
Rules can have multiple versions, even within one ruleset, and security rules control which users see
and execute which versions. This facilitates application evolution, testing, and patching.
One Pega Platform system can host multiple applications, multiple organizations, and multiple versions
of one application with minimal concern for conflicts and interference.
Applications can be developed independently from other applications, yet all can depend on common
rules that are locked (and so won't change).

Overview
The inputs to the rule resolution process are:

The key parts of a rule instance being sought, such as its Applies To class and name
The user's ruleset list, assembled when the user logs in
The class hierarchy — the structure of parent classes and subclasses below the ultimate base class
The user's access roles and privileges held, determined by the access group
Security and access control rules, such as Access of Role to Object rules and Privileges
Rule availability — which rules are available, blocked, final, withdrawn, or not available
Whether time and date limitations affect which rules are available for this session
In some cases, the value of a circumstance property

The output of the resolution process is the first rule found that matches all the criteria. (Sometimes no rule
instance is found, and execution stops.) The system then executes the selected rule. Often this causes one
or more additional rules to become needed. These are also found by rule resolution.

The rule resolution process

The steps in the rule resolution process are as follows:

1. Check the Rules Cache.

Using rules already in the rules cache avoids additional database lookups.

If the rule is there, go to Step 8. If not, continue to Step 2.

2. Choose instances with the correct purpose.

The purpose, or "family name" combines all the key properties of a rule, excluding the "defined on"
class.

For an activity rule, the key properties include:

the Applies To class that the activity is defined on

the activity name

The purpose in this case is the activity name.

For a Field Value, the key properties include:

the Applies To class, as above

the Field Name
the Field Value

The purpose in this case is the Field Name plus the Field Value, for example "
pyActionPrompt.ViewHistory ".

The system chooses all items of the appropriate purpose and puts them in a temporary list.

3. Discard rules where Availability = No.

 The system drops unavailable rules from the temporary list.

4. Discard inapplicable rulesets and versions.

The system drops from the list rules that belong to rulesets and versions that are not enabled for the
current requestor. For instance, if the user's profile includes the ruleset version ThisRuleSet: 05-01,
rules belonging to ThisRuleSet: 04- or ThisRuleSet: 06- are dropped.

5. Discard all candidates not defined in a class in the 'ancestor tree'.

Only rules found in classes from which the current class descends by either pattern or direct
inheritance will be retained in the list.

Note: This step is not used for rules which do not have the Use class-based inheritance to arrive at
the correct rule to execute check box selected in their class definition.
6. Rank remaining stack of rule candidates and discard the choices after the first base rule.

The system ranks the remaining rules on the list in order of

Class
Ruleset - note that default rules that have been saved to a branch or privately checked out are in
their own ruleset.
Circumstance
Circumstance Date
Date/Time Range
Version

The following example shows rules ranked from top to bottom. Rules that have been designated as a
base rule are indicated as such.

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

Note that:

The ruleset and version rankings are based on the ordered list in the user's profile.
A rule with a specific qualifier ranks higher than one with no qualifier.
Circumstanced rules rank alphabetically by Circumstance value.
Circumstance Dates rank in descending value.
Date/Time ranges rank first by their end-date (in ascending order) and then by their start-date (in
descending order).
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 are not ranked by class.

In the above example, if the MyRule is the rule being searched for, the match is at line 3, and all rules
below line 3 are discarded.

7. Set the cache.

The process adds the rules that remain on the list to the cache as being selectable for use.

8. Find the best instance and check for duplicates.

The process searches down the list for the first rule that:

exactly matches a Circumstanced Rule

has the correct Circumstanced Date
is in the correct Date/Time Range
is the default Rule, with no qualifiers

When it finds a rule that matches these conditions, the process checks whether the next rule in the list
 is equally correct. If it is, the process sends a message that there are duplicate rules in the system and
stops processing.

If no duplicates are found, the system prepares to use the rule that matched the listed conditions.

9. Check Availability is not Blocked.

The process checks Availability again, to see whether it is set to Blocked for this rule. If it is, the
system sends a message that it could not find an appropriate rule to use.

10. Verify requestor is authorized to see the rule.

The process finally verifies that the requestor has authorization to access the selected rule. If so, the
system uses it. If not, it sends a message that it could not find an appropriate rule to use.

Example
Your use of an application can cause Pega Platform to search for a flow named Repair in the class Work-
Contract-Application-Complete.

The system first examines in the Work-Contract-Application-Complete class, and then (if no match is found)
searches higher classes in the class hierarchy. Only flows belonging to rulesets and versions that are
present on your ruleset list are candidates.

Exceptions
A few rule types have instances that are not associated with a ruleset and version and no rule resolution
processing occurs when an instance of these classes is needed. For example, access roles ( Rule-Access-
Role-Name rule type) must have names that are unique system-wide.

Additionally, some other 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.

Designing applications for reuse and extension

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
 Ruleset operator. Such rules are not visible to any requestor except those of operators
Layer who have the Allow Rule Checkout? checkNotesbox selected on the Security tab of the
types
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- A version of the foundation rulesets.
NN

Internationalization and localization

Rule resolution

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)

Rule resolution

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.

Rule resolution

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.

Rule resolution

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.

Creating a specialized or circumstance rule

You can create a specialized or circumstance rule to create a variant of the rule that can be triggered
only conditionally. The created rule is resolved and active only when the specified conditions are met.
Create specialized or circumstance rules to address dynamic business requirements without changing
the core logic every time. For information about rule resolution exceptions and how they might affect
circumstance rules, see .

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.

Skim to create a higher version

Skimming creates rules for a major or minor RuleSet version by copying selected rules of lower
numbered versions of the same RuleSet on the same Pega Platform system.

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.

Designing applications for reuse and extension

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.

Changing the scope of rules

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.

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

2. In the header of the form, next to the short description, click the rule status or availability label.
3. 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.
 Available
The rule is considered during rule resolution.
Not available
The rule is excluded from rule resolution, and validation logic is disabled so that you can continue
to edit the rule even if there are errors.
Blocked
The rule is considered during rule resolution but stops processing and returns an error to the user
if it is selected.
Final
The rule is considered during rule resolution but users cannot extend the rule by copying it to a
different ruleset, unless the ruleset is a higher version of the current ruleset.
Withdrawn
The rule and all instances with the same name, in previous versions of the same major-version
ruleset, are excluded from rule resolution.

4. In the Status list, select an option to indicate how users interact with the rule.

API
Users provide standard input parameters to this rule and receive standard return values or
results.
Deprecated
Users are discouraged from using this rule, because it is no longer supported.
Extension
Users can override the rule to provide custom functionality.
Template
Users can select this rule as a starting point to save time when they create a rule.

5. Click OK.
6. 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.

Extension points
Base rules

Changing the scope of rules

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

Setting rule status and availability

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

Setting rule status and availability

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

Setting rule status and availability

Creating a specialized or circumstance rule

You can create a specialized or circumstance rule to create a variant of the rule that can be triggered only
conditionally. The created rule is resolved and active only when the specified conditions are met. Create
specialized or circumstance rules to address dynamic business requirements without changing the core
logic every time. For information about rule resolution exceptions and how they might affect circumstance
rules, see Rule resolution exceptions.

The Save As and Specialize by toolbar tools are restricted to those users who hold the privilege
@baseclass.ToolbarFull or @baseclass.ToolbarSaveAs.

Because the Specialization forms share most of the fields and functionality on the Create form, only
exceptions and special cases are outlined in this topic.

1. On the rule form, complete one of the following steps.

Create a rule that is specialized by class or ruleset.

1. Select Save as > Specialize by class or ruleset .

2. Provide a name for the specialized rule.
Create a circumstance rule.

1. On the rule form, click Save as > Specialize by circumstance.

2. Enter a name for the circumstance rule.
3. Select one of the following types of circumstance: Template or Property and Date .
Click Template to create a template rule circumstance (by multiple properties) and
then provide a template and a definition against which the template is evaluated. You
must have at least one circumstance template rule created before you use it for
circumstancing.

Click Property and Date to create a circumstance of a rule by a property, date, or a

combination of both.
 To create a property circumstance rule, provide the name of a property (for
example, .pyStateName ) in the Property list and its expected value within
quotation marks (for example, “MA”) in the Value box.
To create a date circumstance rule, enter a Date type property, start date, end
date, or a combination of all of the options.

Date combinations and business requirements lists the possible date combinations and
the business-logic requirements they meet.

If you do not specify a date property, the specified time period is always evaluated
against the current system date.

This rule is active during the specified time interval. 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. Of these, if multiple remaining candidate rules have the same end date, the
application picks the candidate with the most recent start date.

2. 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.
3. Update the values in the Context, Apply to, and Add to ruleset lists as appropriate.
4. Click Create and open .

Creating a circumstance template

Create a circumstance template to specialize a rule by more than one feature.

Creating a circumstance definition

You can create a circumstance definition to evaluate properties in a circumstance template.

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.

Date combinations and business requirements

Setting rule status and availability
Creating a rule
Circumstance rule examples
Contrasting time-qualified rules and historical processing
Circumstance templates

Changing the scope of rules

Creating a circumstance template

Create a circumstance template to specialize a rule by more than one feature.
 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 flow.
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. Select the Context.
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.
3. Click Create and open .
4. On the Template tab, list the properties that circumstance definitions can evaluate.
a. Click the Add a row icon.
b. In the Property field, press the Down Arrow key, and then select the name of a property in your
application.
5. Click Save.
6. Control the order in which the circumstance definitions for this template run.
a. On the Definitions tab, ensure that there are at least two circumstance definitions listed in the
All Definitions section.
You may need to wait for your development team to create circumstance definitions that are
associated with your circumstance template.
b. In the Priority Definitions section, click the Add a row icon.
c. In the field that is displayed, press the Down Arrow key, and then select the name of a
circumstance definition.
d. Drag a field to a different position in the list to change its run-time priority.
e. Click Save.

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.

Creating a specialized or circumstance rule

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 template

Creating a circumstance definition
You can create a circumstance definition to evaluate properties in a circumstance template.

Before you begin:

Check whether at least one circumstance template is defined in your application.

Make sure that the PegaRULES database supports access by developers to create circumstance
definitions. For more information, see Database Name form — Completing the Database tab.

Ensure that your changes do not exceed column thresholds. See the Pega Community article
Troubleshooting: "Exceeds the maximum number of columns" when creating a Circumstance
Definition rule .

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
flow.
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
provide a unique value in the Identifier field.
c. In the Template Name field, press the Down Arrow key, and then select the circumstance
template that your circumstance definition implements.
d. Select the Context.
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.
3. Click Create and open .
4. On the Definition tab, add conditions to the Apply this definition table that evaluate the properties
from the circumstance template.
a. Click each column heading to choose which operations it supports.
To reset the operations for a column, clear the Use Range check box, and then select = from the
Use Operator list.

For columns that require a single operation, select an operator from the Use Operator list.

For columns that require a range, select the Use Range check box, and then choose
operators from the Starting Range and End Range lists.

b. Click the Insert Row After icon.

c. For each column in the row, enter a property or an expression that evaluates properties.
d. Drag rows to change the order in which your application evaluates them at run time.As a best
practice, list the more likely outcomes in rows at the top of the table.
5. Click Show conflicts to test the completeness or consistency of your conditions.
6. Click Save.

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.

Creating a specialized or circumstance rule

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.

Base rules
Redirected rule
Creating a specialized or circumstance rule
Finding rules by circumstance
Rule resolution
Circumstance templates
Circumstance definitions

Creating a circumstance definition

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

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

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

Definition Table

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

Creating a circumstance definition

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 specialized or circumstance rule

Creating a specialized or circumstance 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).

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 specialized or circumstance rule

Creating a redirected rule

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 specialized or circumstance rule

Setting rule status and availability
Circumstance rule examples

Creating a specialized or circumstance rule

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 specialized or circumstance rule

Setting rule status and availability
Circumstance rule examples

Creating a specialized or circumstance rule

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.

Creating a specialized or circumstance rule

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

Changing the scope of rules

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 input parameters of a rule

Defining the pages and classes of a rule

Many types of rules can access or update information on various clipboard pages when they run. Most of
these rule types include a Pages & Classes tab that you can use to provide important information about
what your clipboard pages will look like during execution.

Setting up rule prompting during when you configure forms. For example, if you specified that a page
belongs to the Work-class in the Pages & Classes tab of an activity, when the page is used as a step
page, prompting shows results from the Work- class.
Configuring rule validation. The information specified in the Pages and Classes tab defines how rule
references are validated during rule validation.
Applying the default class for list elements. When you define a list or group page on the Pages and
Classes tab, the system automatically sets the class of those elements when new entries are added.

Guidelines
To complete a Pages & Classes tab, follow these guidelines:

Leave this tab blank if the other tabs of the rule do not reference any pages.
Complete this tab to describe the clipboard context expected at run time.
 Page names are case-sensitive, so be sure to match the case of the page name.
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

Changing the scope of rules

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 )

Thread
A named page of class Code-Pega-Thread, identifies a named context of clipboard pages.
page (
The first Thread for a requestor is named STANDARD.
pxThread )

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.
 Name Contains information from the requestor's
OperatorID
Page Operator ID ( Data-Admin-Operator-ID class). This
Description
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
Clipboard tool
Using the Clipboard tool

Defining the pages and classes of a rule

Skim to create a higher version

Skimming creates rules for a major or minor RuleSet version by copying selected rules of lower numbered
versions of the same RuleSet on the same Pega Platform system.

Skimming collects the highest version of every rule in the RuleSet (except as noted below) and copies them
to a new major or minor version of that RuleSet on the same system, with patch version 01. Skimming
applies mainly to rule resolved rules, and there are exceptions to what gets skimmed based on the
availability of the rule as well as the type of skim being performed.

Traditionally, there are two types of Skims, Major and Minor. These reflect the tri-partite naming convention
for ruleset versions, Major-Minor-Patch. During a Minor skim, rules are stored in a higher Minor version, and
during a Major skim, rules are stored in a higher Major version.

Examples
Major: Skimming rules in 06-05-01 through 06-09-25 into 07-01-01

Minor: Skimming rules in 06-05-01 through 06-09-25 into 06-10-01

Major Skim
During a major skim, rules with Availability of 'Yes', 'Blocked', and 'Final' are carried forward. Rules with
availability of 'No' (not available) or 'Withdrawn' are filtered out. Blocked rules are carried forward because
a Blocked rule can block rules in other rulesets, and that relationship should be maintained if it exists.

Minor Skim
During a minor skim, rules with Availability of 'Yes', 'Blocked', 'Withdrawn' and 'Final' are carried forward.
Rules with availability of 'No' (shown as 'Not Available' in the table below) are filtered out.

Table of rules carried forward

The following table displays which rules are carried forward, based on availability.

Available Not Available Final Withdrawn Blocked

Major Yes No Yes No Yes

Minor Yes No Yes Yes Yes

Preparations
Before performing the operation, complete these steps:
 1. Select Dev Studio > Application > Development > Checked Out Rules. Complete the parameters and
click Run. Review the resulting report to confirm that no rules from that RuleSet version are checked
out. Confirm that none of the rules to be skimmed are checked out.
2. If desired, secure each version below the new version, so the rules associated with that version cannot
later be modified or deleted.
3. Select Dev Studio > System > Refactor> RuleSets > Skim a RuleSet to begin the skim operation.
4. After the operation completes, update application rules, the Requires RuleSets and Versions
prerequisites array in RuleSet version rules, and access groups to reference the new major version.
5. Log off and log in to access the new version.

Completing the form

To skim to a new version:

1. Select a radio button to indicate whether the newly created version is to be a major version (NN-01-
01) or a minor version (NN-MM-01).
2. Select a RuleSet to be skimmed in the RuleSet field. You can skim only RuleSets appearing on your
RuleSet list.
3. Select an existing major version in the From Major Version field.
4. Select a version in the Starting Version and Ending Version fields.
5. Enter the version number to be created, consistent with the radio button you selected in Step 1.
6. Click Skim to begin processing. This may take several minutes.
7. The system creates a new RuleSet version and begins copying rules. A status area shows progress and
the results of the skim.
8. 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.
9. Click Close to exit.

A "No records found" message indicates that the rules associated with the RuleSet have no version and so
were not altered.

Follow-up tasks
After the skim operation completes, these steps may be useful:

1. Research and resolve errors reported by the skim operation.

2. Update access groups or application rules to make the new major version available to appropriate
users.
3. To ensure that all users access only the new major version, delete rules in the lower major version

See below: Class rules do not have a version. Do not delete Class rules (or other rules that have no version).
In some organizations, policies may prohibit deleting old rules, even if they are not in use.

4. Optionally, delete rules after skimming

Skimming does not delete any rules; the rules it copies to make the new version remain unaltered.

When the skim operation completes, update each existing RuleSet Version that was skimmed to secure it
by checking the Lock this Version? field on the Security tab. This ensures that from then on, developers can
add or update rules only in the newly created version.

In addition to locking the RuleSet versions, in some organizations, administrators prefer to delete the rules
in lower versions after the versions are skimmed. Deleting no-longer-used rules can benefit performance,
because rule resolution has fewer rules to search through.

Of course, do not delete any class rules or library rules; rules of these two types (and others listed below)
don't belong to a version and are needed while any version is in use. Use the Export Archive tool to back up
a RuleSet version before deleting it.

In some organizations, compliance and audit requirements prohibit deleting rules, even those no longer in
use.

Notes
Blocked rules are always skimmed. Withdrawn rules are skimmed during a minor skim, but not a major
skim.

Rules in major versions below the major version you enter are not copied. For example, if you skim 02-ZZ-
ZZ into 03-01-01, any rules in version 01-ZZ-ZZ are ignored.

Rules of these types do not have versions and therefore are unaffected by skim processing:

Application
Access of Role to Object
Class
Access Deny
RuleSet
Library
RuleSet Version

Skimming does not delete any rules. Skimming copies but does not update or delete rules in the source
versions.

Skimming does not validate the copied rules, nor compile any Java. For rules of rule types that produce
compiled Java, compilation occurs when the rule is first assembled and executed.

The Skim option is available only to users who have access to the zipMoveSkim privilege. The standard
access role PegaRULES:SysAdm4 provides this privilege.

The update history of the new, skimmed rule contains only one instance, reflecting the date and time it was
created through the skim operation. The history of the source rule remains available and unchanged.

Changing the scope of rules

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

Changing the scope of rules

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.

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)
 Designing applications for reuse and extension

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

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.

Checking out a rule

Performing a private edit

To ensure that your application meets the unique needs of your customers, you can modify a rule that is
unavailable for regular checkout by performing a private edit. Check out rules as private edits to edit rules
that belong to locked rulesets.

Private edits are useful for quick debugging without interrupting other team members, because during a
private edit other system architects can edit a rule at the same time.
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

Private checkout

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.

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

Checking out a rule

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

Checking out a rule

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

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

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

Checking out a rule

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

Checking out 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 out a rule

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

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.

Checking in a rule

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. See
Standard activities — Extension points.

Configuring the rule check-in approval process

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

Checking in a rule

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

Designing applications for reuse and extension

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

Restoring the earlier state of a rule

Finding deprecated rules in sections

Find sections that use deprecated rules by using an application upgrade utility. Once found, these legacy
rules can be updated to newer rules.

Your application might contain sections that use legacy rules or images. Legacy rules and images have
been deprecated or upgraded with newer rules. Update or refactor legacy rules to use the latest Platform
rules. You can search for legacy rules by using the Application Upgrade Utilities. Note: Images are found
using index references and the results are compared using rules names. This means that even after you fix
an image in a section, the rule may still be listed in the report

1. Click Configure System Release Upgrade Upgrade tools .

2. Click the List rules using legacy rules link.
3. From the list of rules, select a rule to open it. From here you can upgrade or refactor the rule.

Migration tools
Importing the legacy ruleset from the Resource Kit

Designing applications for reuse and extension

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.

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 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 .

Designing applications for reuse and extension

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.

Exploring rules in your application

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

Exploring rules in your application

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.

Exploring rules in your application

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.

Exploring rules in your application

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

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.

Exploring rules in your application

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

Exploring rules in your application

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
Select a System drop-down the next time you use this wizard.

Username Enter a valid operator ID for the target server.

Password Enter the user password for the operator ID you specified.

Next >> Click to continue to the next step of the wizard.

Cancel Click to exit the wizard.

Comparing rules by system

Using the Rulebase Compare wizard — Step 2: Select Instances

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

Comparing rules by system

 Using the Rulebase Compare wizard — Step 1: Enter System Info
Using the Rulebase Compare wizard - Step 3: Display Summary

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.

Comparing rules by system

Using the Rulebase Compare wizard — Step 2: Select Instances
Using the Rulebase Compare wizard — Step 4: Display Report

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.

Comparing rules by system

Using the Rulebase Compare wizard - Step 3: Display Summary

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.

Exploring rules in your application

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.
 Menu Option
Return results based on words Result
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
exists in searched text.

The string abc def exists

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 abc or 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*
Syntax sent to words beginning with
Entered text Search method defMatch
existsreturned if
in searched
Elasticsearch
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.

Keystores

Exploring rules in your application

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

Exploring rules in your application

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.

Application Inventory landing page

Reporting on rules

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
Application Inventory landing page

Reporting on rules

Reviewing exposed properties

To enhance record selection operations for reporting, certain single value properties are stored as exposed
columns in an application. You can review which properties are exposed in your appliction.

You can use exposed properties to search for archived cases.

1. Click Configure > Data Model > Classes & Properties > Database Class Mappings.
2. Locate your class in the Database Class Mappings table.
3. In your class's row, click the number in the Exposed/Mapped column to view exposed properties for
that class.

Reporting

Reporting on rules

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 history

Exploring rules in your application

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.

Exploring rules in your application

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.

Exploring rules in your application

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

Exploring rules in your application

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

Designing applications for reuse and extension

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

Delegating a rule or data type

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

Delegating a rule or data type

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

Delegating a rule or data type

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

Delegating a rule or data type

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.

access group
Delegating a data type

Delegating a rule or 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

Delegating a rule or data type

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.

Migration tools
Finding deprecated rules in sections

Designing applications for reuse and extension

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.

Keystores
Data Transforms

Designing applications for reuse and extension

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

Referencing properties

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. 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.

2. 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.
3. If you configure a single page or page list property, in the Data access section, define how property
sources values:
Choices Actions
 Users provide
Choices Actions
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.
4. Click Save.

Referencing properties

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 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.

Configuring an application to use branches and branch rulesets

To use branches in your application, you create a development application that is built on your
production application. You create rules and save them in your development application, creating
branch rulesets. You can then work with branches in a number of ways, such as creating branch
reviews and merging branches.

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.

Understanding continuous integration and delivery pipelines

Unit testing individual rules
Troubleshooting tools and techniques

Designing applications for reuse and extension

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 Creating branches.

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.

Creating branches
Understanding continuous integration and delivery pipelines
Troubleshooting tools and techniques

Branched application development

Configuring an application to use branches and branch rulesets

To use branches in your application, you create a development application that is built on your production
application. You create rules and save them in your development application, creating branch rulesets. You
can then work with branches in a number of 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 production application. See Creating a team
application for more information.
2. Add branches to your application, into which you can save the rules that you are developing. See
Adding branches to your application for more information.
3. Optional: Create a repository and configure your main development system (remote system of
record) to use branches with repositories on which you can store and test branches. For more
information, see Creating a repository.
4. Work with branches in a number of ways; for example, create a review, merge branches, or delete
branches from the system. For more information, see Branch operations.

Adding branches to your application

You can create branches in your development application, add a branch that exists in a system, or add
a branch from a repository that is configured on a remote development system.

Branches and branch rulesets

Branched application development

Adding branches to your application

You can create branches in your development application, add a branch that exists in a system, or add a
branch from a repository that is configured on a remote development system.

After you add branches, you can modify the order in which the system runs them, set the top-level branch
as editable at run time, and add rules to branches. After you add rules to branches, the system
automatically creates branch rulesets.

Creating branches

Create branches in your application so that you can develop rules in them. The system automatically
creates branch rulesets when you save a rule in to the branch.

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.

Adding a branch from a repository

Configuring an application to use branches and branch rulesets

Creating branches
Create branches in your application so that you can develop rules in them. The system automatically
creates branch rulesets when you save a rule in to the branch.

1. In the navigation panel, click App, and then click Branches.

2. Right-click the application to which you want to add the branch and click Create branch.
3. In the Branch name field, enter a name for the branch. You must start the name with a letter.
4. Optional: In the Description field, enter a description for the branch.
5. Click Submit.
6. Optional: 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.
7. 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 Live
UI for more information.
8. 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. See Rule development
in branches for more information.

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.
 Adding branches to your application

Adding branches to your application

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.

Adding branches to your application

Creating branches

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

Keystores
Keystores
Merging branches into target rulesets

Rule development in branches

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 branches to your application

Adding 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

After teams have completed rule development in a branch, you can use the Merge Branches wizard to
move the contents of the branch into the base ruleset of the development application.

Branches and branch rulesets

 Integrating with file and content management systems

Branched application development

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

Branch operations

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

Creating unit test cases
Understanding branch quality metrics

Branch operations

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

Viewing branch quality and branch contents

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 Live
UI for more information.
4. Click Save.

Adding branches to your application

Branches and branch rulesets

Branch operations

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

Branch operations

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

Branch operations

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

Branch operations

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 operations

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

Branch operations

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

Branch reviews

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

Branch reviews

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

Branch reviews

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

Branch reviews

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

Branch reviews

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

Branch reviews

Merging branches into target rulesets

After teams have completed rule development in a branch, you can use the Merge Branches wizard to
move the contents of the branch into the base ruleset of the development application.

As a best practice, the system administrator should create a new ruleset version for the base ruleset,
independent of the wizard. Individual teams should develop rules in their specific branches and then merge
those branches into the existing base ruleset version that was created by the administrator. This process
gives administrators better control over versions.

1. Check all rules into their base rulesets before you merge them.
2. Optional: Check if there are any potential conflicts to address before merging branches. For more
information, see Viewing branch information.
3. Optional: As a best practice, lock a branch after development is complete so that no more changes
can be made. For more information, see Locking a branch.
4. Optional: Check if there are any potential conflicts to address before merging branches. For more
information, see Viewing branch information.
5. In the navigation panel, click App, and then click Branches.
6. Do one of the following actions:
To merge a single branch, right-click the branch and click Merge.
To merge multiple branche, right-click your application, click Merge, and select all the branche
that you want to merge.
7. If there are conflicts or warnings, the Target ruleset section displays a link that opens the Conflicts and
Warnings window. You must resolve conflicts before you can merge branches. For more information,
see Conflicts and warnings in the Merge Branches wizard.
8. From the drop-down box next to the Target version section, select the base ruleset version into
which rules are merged. Complete one of the following actions:
Select Create new version to create the new ruleset version in the base ruleset during the
 merge.
Select an existing base ruleset version in which you want to merge the rules.
9. Click Merge. Details about the merge are displayed when the merge is completed, such as whether
the merge was successful, how many rules were merged, 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.

Merge branches customization

You can enhance the merge process for your development team in various ways to comply with your
organization's policies and procedures. You can:

Branches and branch rulesets

Branch operations

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

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

The rule in a Base ruleset XYZ has two locked ruleset versions, 01-01-01 and 01-01-02. TeamA
lower base branches XYZ into their Story-A branch, and TeamB branches XYZ into their BugFix-1
ruleset branch. TeamB's work is a bug fix for version 01-01-01, and they complete their work
version has and merge their BugFix-1 branch with the changed rules for base ruleset XYZ into 01-01-
been recently 01. Then TeamA starts the wizard to merge their Story-A branch by creating a new
 updated.
Conflict version for base ruleset XYZ. The wizard reports a conflict because the rule was updated
in ruleset version 01-01-01Example
(a lowerof how this
version) byoccurs
TeamB prior to TeamA's merge.
situation
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

Conflicts and warnings in the Merge Branches wizard

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

Conflicts and warnings in the Merge Branches wizard

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
situation Example of how this occurs Recommended steps

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
next to the caution icon to open the other rule
and directly examine it.
The 2. Review all differences between the rules, and
 corresponding
Warning In this situation, the rule exists in use the Related Rules display to assess the
base rule
situation another branch
Example ruleset
of how this which
occurswill impact of the differences.
Recommended steps
exists in later be merged into a different 3. Contact the owner of the other branch, or the
another ruleset than the one the author of the other branched rule, and
branch corresponding base rule is in. A discuss why a rule with the same name exists
ruleset, which team has branched a base ruleset in two different rulesets, and determine
is branched that is different than the one you are whether there are reasons for both to exist or
from a merging, and has copied the base whether one should be removed.
different rule that corresponds to your branch If the base rulesets are for different
ruleset than rule into their branch ruleset. purposes and will not be run
your branch concurrently, then continue with your
ruleset. 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

Conflicts and warnings in the Merge Branches wizard

Merge branches customization

You can enhance the merge process for your development team in various ways to comply with your
organization's policies and procedures. You can:

Add preprocessing behavior

Add postprocessing behavior
Customize validation on the inputs in the Merge Branches wizard user interface

For preprocessing and postprocessing behavior, the flow rule that governs this process has two extension
points as subprocesses at which you can add custom steps: pypre-mergeInstances and
pyPostMergeInstances. By saving a copy of the standard rule and customizing your copy, you can override
the generic behavior with custom behavior; for example:
 Preprocessing: By customizing a copy of pypre-mergeInstances, you can provide processing that
occurs before the wizard starts, such as verifying that a user's operator ID is performing the merge
instead of a generic account.
Postprocessing: By customizing a copy of pyPostMergeInstances, you can provide processing that
occurs after the wizard completes, such as sending an email notifying the team about the status of the
merge.

For customized validation on inputs into the wizard user interface, you can override the extension point
activity pyValidateMergeOptions.

Merging branches into target rulesets

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.
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 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 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

Types of UI rules include harnesses and sections.

Unit testing data model rules

Types of data model rules include data pages and data transforms.

Unit testing decision rules

Decision rules are used for configuring decision data flows for actions such as loading customer data,
executing a decision strategy, and writing results into interaction history. Types of decision rules
include decision tables, decision trees, when rules, map values, collections, and declare expressions.

Unit testing process rules

 Types of process rules include flows and case types.

Unit testing report rules

Report rules include report definitions.

Unit testing technical rules

Types of technical rules include activities.

Unit testing parse rules

Unit testing service rules
Clipboard pages created by the Run Rule feature

After running a rule, you can open the Clipboard tool and examine the output as it appears on the
resulting clipboard pages. The Run Rule operation creates the following pages:

Designing applications for reuse and extension

Unit testing UI rules

Types of UI rules include 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 individual rules

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 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.

harnesses
 Unit testing UI rules

Unit testing a section

Applicable to Theme UI-Kit applications

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. For more information, see
Sections - Completing the Create or Save As form. 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.

Sections

Unit testing UI rules

Unit testing data model rules

Types of data model rules include 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 individual rules

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 Decision Decision Table , and then select the
data page that you want to open.
 2. Click Actions Run .
3. From the Thread list in the Run context pane, select the thread in which you want to run the rule.
4. In the main test page, enter values for parameters, if any, to pass to the rule.
5. Select the Flush all instances of this data page before execution check box to delete any
existing instances of the selected data page.
6. Click Run.
7. 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.
8. 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.
9. 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

Unit testing data model 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

Converting unit tests to test cases
Viewing test case results

Unit testing a data page

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

Unit testing data model rules

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

Adding a data page to a data type
Running a unit test case
Converting unit tests to test cases

Unit testing data model rules

Unit testing decision rules

Decision rules are used for configuring decision data flows for actions such as loading customer data,
executing a decision strategy, and writing results into interaction history. Types of decision rules include
decision 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 individual rules

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.
7. 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.
8. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
9. 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

Unit testing decision rules

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 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.
7. 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.
8. To convert the test into a Pega unit test case, click Convert to Test. For more information, see
Creating unit test cases for rules.
9. 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

Unit testing decision rules

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 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. 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. 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.
9. 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

Unit testing decision rules

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 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 decision rules

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 decision rules

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 decision 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 decision rules

Unit testing process rules

Types of process rules include 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 individual rules

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.

Keystores
Creating binary file rules
Viewing generated Java code of Access When rules

Unit testing process 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

Keystores

Unit testing process rules

Unit testing report rules

Report rules include 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 individual rules

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 Definition rule form

Unit testing individual rules
Creating unit test cases for rules

Unit testing report rules

Unit testing technical rules

Types of technical rules include 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 individual rules

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.

Keystores
Unit testing individual rules
Using the Clipboard tool
Opening a unit test case
Application debugging using the Tracer tool

Unit testing technical rules

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.

Unit testing an activity

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 an activity

Unit testing parse 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 will eventually operate.

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 it will ultimately operate.

Unit testing individual 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 will eventually operate.

Preparation
For a simple test, obtain 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 Delimited form.

2. Click the Run toolbar button or the equivalent keyboard shortcut CTRL + R. A guided 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 to evaluate the rule. An XML document appears in a new window, showing properties
and the corresponding parsed values. The clipboard is not altered; no properties are updated.

Keystores

Unit testing parse 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.

Keystores

Unit testing parse rules

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 it will ultimately operate.

Preparation
For a simple test, obtain an XML document that contains test data. You can choose to type or paste the
document 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 Structured form.

2. Click Run or the equivalent keyboard shortcut CTRL + R. A test window opens.
3. Select a radio button to indicate whether a new empty page or an existing page is to provide input
property values for the test.
4. Select a radio button to indicate the source of test data.
5. 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.
6. Click Execute. The resulting parsed XML document appears in a new window. The clipboard is not
altered.

The parseState object and debugging

As it executes, a Parse Structured rule creates and maintains a Java object in memory named parseState. This
corresponds to a method variable in the generated Java.

This object is not visible through the Tracer or the Clipboard tool, but you can use Public API functions to
examine it. To do this, include a Java step containing the Public API call:

myStepPage.putString("debug3", Long.toString(parseState.getStreamOffset()) );

where debug3 is a Single Value property. This function places the byte offset position of the Java object into a
clipboard value. You can review the clipboard value with the Tracer or Clipboard tool.

Four Pega Platform methods operate on the parseState object:

Parse-Byte-Pos (for byte streams)

Parse-Char-Pos (for character streams)
Parse-Fixed-Binary (for byte streams)
Parse-Packed-Decimal (for byte streams)

The result of each method is stored in parseState.lastToken (which can be accessed in a Java step) and optionally
is stored as a property value.

The parseState object is defined in the PublicAPI Interface

com.pega.pegarules.pub.runtime

This facility is based on java.io.* capabilities (not the newer java.nio.* capabilities). The PublicAPI includes
methods to query or operate on the object.
Using the Tracer
To trace the start and end of Parse Structured rule executions:

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.

Keystores

Unit testing parse rules

Unit testing service 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.

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.

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
Enter Request parameters are scalar values, such as strings, numbers, or booleans.
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
Field Value field a literal constant value for each EJB method parameter declared on the
Description
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.

Keystores

Unit testing service rules

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.

Keystores
Tracing services

Unit testing service rules

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 service 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.

Keystores

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
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.

Keystores

Unit testing service rules

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
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 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 service rules

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:
 Field Use current requestor context — Use your current requestor session (including
Description
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 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.

Keystores

Unit testing service rules

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
Field 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 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.

Keystores

Unit testing service rules

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
Field your RuleSet list, Description
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 Message Data
of the Request tab contains only scalar values, such as strings, numbers, or
Enter Request
Boolean values.
Data
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 service rules

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 ,
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 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.

Keystores

Unit testing service rules

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
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.
 Keystores

Unit testing service rules

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.
 Field Select one of the following to define the source of request data values for this
Description
test:
Enter Request Specify individual request values -- This option appears only when all
Data elements of the message are simple text values, not arrays or complex
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 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

Service SOAP rules - Completing the Create, Save As, or Specialization form
More about Service SOAP rules

Unit testing service rules

Clipboard pages created by the Run Rule feature

After running a rule, you can open the Clipboard tool and examine the output as it appears on the resulting
clipboard pages. The Run Rule operation creates the following pages:

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

Unit testing individual rules

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.

 Designing applications for reuse and extension

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

Managing relevant records

Manage your relevant records to consolidate records that are specific to your cases and data types.
Marking records as relevant can 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 and components

Managing relevant records

Manage your relevant records to consolidate records that are specific to your cases and data types.
Marking records as relevant can reduce time-consuming searching through unrelated records in your cases.

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, based on how you plan to use the
rule.
By default, only active relevant records for the selected class are displayed.
3. Do 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 mark a record as active or inactive for the selected class, click the Actions icon on the
rightmost side of the row.
To display records that are inherited from the hierarchy of the specified class, 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 marked as relevant.
To mark an inherited record from another class as active or inactive for the selected class, click
the Actions icon on the rightmost side of the row.

Relevant records for rule reuse

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
Configuring views for cases

Relevant records for rule reuse

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.

Relevant records for rule reuse

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.

Relevant records for rule reuse

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

Relevant records for rule reuse

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

Managing relevant records and 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

Installing 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

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

Installing components

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
 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.

Creating a 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).

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.

Creating a component

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
 Installing components

Calculating values and making decisions

To provide automated solutions for your application users, define automatic was of making decisions and
calculating values in your business processes.

For example, you can create a decision table that examines values that a user provide to apply the best
solution in the process.

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.

Building expressions with the Expression Builder

Author expressions using the Expression Builder by completing the following steps:

Designing applications for reuse and extension

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 following tabs are available on this form:

Definition
Settings
Test Cases

Data transforms are useful:

When using data pages to manage application data (see the Where referenced section below).
In activities, when:
Copying a clipboard page to make a new page.
Mapping properties (and their values) on one page to another, existing page.
 Mapping properties (and their values) on one page to a new page.
On a given clipboard page, defining one or more initial properties on that page and setting their
values. A data transform can set many property values on a page in one processing step.

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 than the clipboard properties to which you are mapping.
In addition, you can select classes to exclude.

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. For more information, see the Pega
Community article Data virtualization in PRPC.

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
Use these topics to learn about a specific data transform action:

Append and Map To

Append To Otherwise When
Apply Data Transform Remove
Auto-map Set
Exit For Each Page Sort
 For Each Page In Update Page
Otherwise When

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 data transform

To speed up the development and make application maintenance more convenient, 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

Data Transform form - Append to action
Data Transform form - Apply Data Transform action
Data Transform form - Auto-map action
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
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, during
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

Apply-DataTransform method
Rules development

Calculating values and making decisions

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 specialized or circumstance rule
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

Data Transforms

Configuring data transform

To speed up the development and make application maintenance more convenient, 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.
3. Optional: To manually set the name of your data transform, in the Identifier section, click Edit.
By default, the system automatically populates this field with a read-only value based on the sentence
that you enter in the Identifier field. The system ignores spaces and special characters.
4. In the Additional configuration options, select a data model format for your data transform:
If you want to use the Clipboard 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 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 contain the record, and then select
the version number from the list.
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.
For more information about actions available for Clipboard, 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
Configure data target and the source.
transform by using d. In the Source column, specify the source of the selected action.
Clipboard 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 for
transform by using 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.
Configure the data For more information about actions available for JSON see Data transform
transform by using actions for JSON.
JSON d. In the Clipboard column, select the clipboard to use for JSON serialization
or deserialization.
e. If available, in the Relation column, specify the relationship between the
target and the source.
f. In the JSON column, enter the array, object, or simple field name from the
JSON data.
 g. To add more actions to your data transform, click Add element, and then
Choices Actions
repeat steps 8.c through 8.f.
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 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

Configuring data transform

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

Configuring data transform

Data Transform form - Append and Map to action

Usage
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.

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. Then, subsequent children 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 yet exist on the newly created page.

When using 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 when you want to create a new page in the target Page List, and
subsequently create properties on that page.
an existing page – Use when you want 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 when you want 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 says, "each scalar element." You
can specify the clipboard field you want 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 says, "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.

Supported features
You can use the following items in the Append and Map to action:

In the Target, Page List mode properties

In the Source, 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 using this action.

Data Transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

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 Transforms

Data Transform form - Apply Data Transform action

Usage
Use the Apply Data Transform action to apply actions defined in another data transform (the applied data
transform).

To apply the data transform to a specific page, specify a row 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.

In addition, you can only apply a data transform that is a JSON data model format. You cannot apply a data
transform that is a clipboard data model format.

Example
Apply Data Transform

SetShippingInformation

Relationship settings
The Apply Data Transform action has no setting for the Relation field.

Supported features
You can specify the following items in the Apply Data Transform action:

Data transform rule - JSON data transforms can only call other JSON data transforms. Clipboard data
transforms can call any data transform.
Input parameters
Passing the current parameter page

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.

Restrictions
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 runtime),
design-time validation does not check to see if 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 Transforms

Data Transform form - Auto-map action

Usage
Use the Auto-map action to contextually automatically map data from JSON to the clipboard or the
clipboard to JSON. Use this action with Page or Page List properties that has a data model of the property's
page class exactly matches the JSON data model. The name and type of every child field is exactly 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 on 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

Examples
Auto-map .Customer to person

Auto-map .CustomerList to people

Supported features
Page
Page List

Restrictions
No page groups
No Value Lists or Value Groups

Data Transforms
Data Transforms - Completing the Create, Save As, or Specialization form
More about data transforms

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. See
Property form — Completing the General tab — Page modes for a description of the Lightweight option.

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 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 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 ""

Relationship settings
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 makes no other sort of relationship between the target and source.

Supported features clipboard data model format

When the data model format is clipboard, the Set action supports the following target and source
combinations. 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

Property equal to Property Reference .Department

Property equal to Literal "W-"

Property equal to Expression .FIRSTNAME + " " + .LASTNAME

Property equal to Linked Property Reference .pxCreateOperator.pyUserName

Page equal to Page OrderItems(1) equal to HardwareItems(1)

Use of the following items is supported:

Properties
Literals
Expressions
Parameters specified on the Parameters tab (for example, param.Name )
Page Lists
Page Groups
Value Lists
Value Groups
Keywords: Primary, <APPEND> , param
Function calls (for example, @addToDate(@CurrentDateTime(),1,"","","") )

When the Set action is preceded by an Update Page action that sets the context of the Source to the data
page, in the Source field, you can use values from data pages.

Restrictions
Use of Top and Parent 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 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 Transforms

Data Transform form - Update Page action

Usage
The Update Page action sets the page context for the subsequent (children) steps.

Use the Update Page action when you want to set values on a target page that is different from the data
transform's primary page, and you want 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 children 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 list.

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

Relationship settings
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:

pyCustomer
-pyID
-pyName
-pyEmail
-pyAddress
-pyAddressLine1
-pyAddressLine2
-pyCity
-pyZip

The tree structures match except for the address line fields. line1 on the JSON side is under the address >
addressLines hierarchy, but its corresponding pyAddressLine1 property on the clipboard is directly under pyAddress.
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, then map
individual properties, as shown in the sample below:

Update Page pyAddress For both sides address

Update Page No context change For JSON only addressLines

Set pyAddressLine1 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.
It is not recommended that you use the Top keyword in data transforms. There are situations where
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 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

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 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 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

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, during 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. In the process in which you want to apply a data transform, 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 window, 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

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- pyCopyDefault
 Data work item.
Work-To
Applies pyDefault Provides default initial values
Purpose
for properties in new work items.
transform
Provides default initial values for properties in new work items
Work-Cover- pyDefault
that are covers.

Provides default initial values for properties in new work items

Work-Folder- pyDefault
that are folders.

Provides default initial values for properties in new work items

Work-.RuleCheckin pyDefault
for the rule check-in flow.

PegaSample- Demonstrates entry of a Simple Task work item, not part of a

pyDefault
SimpleTask cover.

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

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

Data Transforms
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

Data Transforms

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 Declare Expression rules - Completing the New or Save As form.

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.

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.

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.

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

Calculating values and making decisions

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

Decision tables

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

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

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

Decision tables

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

Calculating values and making decisions

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
application from candidates with > 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.
e. Select the next branch to display the columns.
 conditions f. Define a nested condition by providing a property or value, a comparator, and a
Choices Actions
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.
Return a
c. Optional: To configure your application to perform an action, click Take actions,
value
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 Perform action.

Perform b. Click Actions.
an c. Click Add a row.
action d. Define an action by setting a value for the action property. For example: Change a
case status by 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

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
 Field Enter a value for the current context, or aDescription
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
arrow to 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
decision tree in the same way.
(action)
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.

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 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.
 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.

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.
Call Decision Tree
(next Select another decision tree. The result of that rule becomes the result of this rule.
value) Call Map 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.

This capability is not available for decision trees that are created in basic mode, or for
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

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

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
arrow to 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

AllowMissingProperties parameter 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.

 Field If you selected Return as the action and the Results tab is not blank, select one of the values
Description
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

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

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:

Allow changes to Populate the Functions Allowed list to restrict the function aliases a user can
function lists select.

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.

Open any function 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
Field Clear this check box to hide the add icon on the Decision tab.
Description
decision tree

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

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.

Property-Map-DecisionTree method
Application debugging using the Tracer tool
About Decision Trees
Creating decision trees
Viewing rule history

About Decision Trees

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 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.

Calculating values and making decisions

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. See Property References in
Expressions.

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

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

About Map Values

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

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

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.)

Property-Map-Value method
Property-Map-ValuePair method
About Map Values

About Map Values

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.

To create a one-dimensional map value, 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

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

About Map Values

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

Rules development

Calculating values and making decisions

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 Decision When .

2. On the When tab, click Create.
3. In the Label field, enter a description of the When rule. For example: IsTaskCompleted
4. 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
5. 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.
6. In the Context section, select an application to which the rule applies.
7. In the Apply to field, select a class to which the rule applies.
8. In the Add to ruleset field, select a ruleset for the rule.
9. 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.
10. Click Create and close.

When Condition rules

More about When Condition rules

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

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

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

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

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

When Condition rules

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.

Displaying all functions in the Expression Builder

By default, the Expression Builder displays only non-internal libraries and functions. You can display all
functions in the system in the system by overriding the pyShowInternalLibrary When rule setting.

Calculating values and making decisions

Displaying all functions in the Expression Builder

By default, the Expression Builder displays only non-internal libraries and functions. You can display all
functions in the system in the system by overriding the pyShowInternalLibrary When rule setting.
 1. In the Dev Studio Search field, enter pyShowInternalLibrary, and press Enter.
2. Open the When rule.
3. Click Save as, select Save As, and save the rule in your application ruleset.
4. On the Conditions tab, click false, click the Actions link, and select Edit.
5. In the Condition dialog box, enter True in the field, and click Submit.
6. Click Save.

Result: All functions in the system appear in the leftmost panel of the Expression Builder.

Building expressions with the Expression Builder

Building expressions with the Expression Builder

Calculating or validating values automatically

To save time and reduce the risk of errors during calculation, provide tools for your application that
calculate and validate values in an automatic way.

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.

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.

Defining conditions in the condition builder

Use the condition builder to define conditions for stages in your workflow or for propositions evaluated
by a proposition filter. You can save custom conditions to the condition library for future use.

Designing applications for reuse and extension

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

Calculating or validating values automatically

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.

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

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
 Field Click the drop-down button to select a boolean expression from the drop-down list. The form
Description
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.

For example, if the constraint is of the form

BoxWidth IS LESS THAN 40

then the message can be associated with the BoxWidth property. If the constraint has the
to form

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

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
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
 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.

Application debugging using the Tracer tool

About Constraints rules
Constraints rules -
Viewing rule history

About Constraints rules

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.

Declare Expression rules - Completing the New or Save As form

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.

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.

Declarative network

The declarative network is an internal data structure that defines the relationship between properties
and whose value is automatically (declaratively) calculated based on changes to other property
values. You can configure and visualize complex relationships using the Declarative Network display,
which shows the target property and all potential inputs that might affect its final value. You can
review relationships that depend on forward chaining or backward chaining.

Expressions
Viewing rule history

Calculating or validating values automatically

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
the form are not defined, the Otherwise value is returned as the value of the rule.
When applied by a Rule Collection
Calculate The target property is computed only when the defined Declare Expression rule is
Value 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
 The target property is computed only when an independent collection rule directly
Field Description
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
is disabled by default. Enable them through changes to the prconfig.xml file or Dynamic
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
Declare Expression rules - Completing the New or Save As form
Viewing rule history
More about Declare Expression rules

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 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.

Select a computation type. The choices available depend on the type of the Target Property
.

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
 Field expression will be used as input. Description
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
the selection list. Enter a pair of 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
 Field a property in the top-level page. (You can use the Parent keyword more than once.)
Description
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.

About Declare Expression rules

About Declare Expression rules

Declare Expression rules - Completing the New or Save As form
Viewing rule history
More about Declare Expression rules

About Declare Expression rules

Declare Expression rules - Completing the New or Save As form

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.

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
Forward chaining does not create embedded pages where none existed before. Declare
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

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.

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
Field Description
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

Declare Expression rules - Completing the New or Save As form
Viewing rule history
More about Declare Expression rules

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.

Business Rules landing page

Property-Seek-Value method
Expressions
Application debugging using the Tracer tool
About Declare Expression rules
Declare Expression rules - Completing the New or Save As form
Viewing rule history

About Declare Expression rules

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

About Declare Expression rules

Declarative network
The declarative network is an internal data structure that defines the relationship between properties and
whose value is automatically (declaratively) calculated based on changes to other property values. You can
configure and visualize complex relationships using the Declarative Network display, which shows the
target property and all potential inputs that might affect its final value. You can review relationships that
depend on forward chaining or backward chaining.

From the Declarative Network display, you can quickly access declare expression rules and the properties
that they reference. You can also use the display to unit test a Declare Expression rule.

This feature requires the Adobe Flash Player plug-in.

Declarative Network display

With the Declarative Network display, you can quickly access the Declare Expression rules and the
properties that it references.

Viewing the declarative network

You can view the declarative network in a tab on the Business Rules landing page, which displays the
target property and all potential inputs that might affect its final value, for a property that applies to a
work type in an application.

Business Rules landing page

About Declare Expression rules

About Declare Expression rules

Declarative Network display

With the Declarative Network display, you can quickly access the Declare Expression rules and the
properties that it references.

Each rectangle in the display represents a property. An F in a box or circle represents a functional
relationship among properties, created by a Declare Expression rule. Properties on the left and above are
dependent on others to the right and below, indicated by lines.

From the Navigation list, you can select Cascade Tree as the style to present dependencies with an
arrow that indicates forward or backward dependencies. (These directions do not indicate forward or
backward chaining.) You can select Basic Tree as the style to see more of a large or complex dependency
network.

The display shows the structure of the relationships but not the results of specific computations. You can
unit test Declare Expression rules by clicking Run ZZZZZ, where ZZZZZ is the name or description of the
target property, and entering values.

Declarative network
Viewing the declarative network
Unit testing a declare expression

Declarative network

Viewing the declarative network

You can view the declarative network in a tab on the Business Rules landing page, which displays the
target property and all potential inputs that might affect its final value, for a property that applies to a work
type in an application.

1. Click Switch Work Pool work pool from the Application menu.
2. Select Configure Process and Rules Business Rules Declarative Network .
3. The Declarative Network displays a list of declarative networks in the current application. You can
choose the following options.
The declarative network name and level (top- level or intermediate). Top-level declarative
networks contain a target property that is not referenced by any other declare expressions.
Intermediate declarative networks contain a property that is referenced by another declare
expression. To open the Declarative Network display, click a declarative network name.
The declare expression used to calculate the declarative network. Click the Declare Expression
icon to open the declare expression rule. Click the property name to open the target property.

Declarative Network display

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

Calculating or validating values automatically

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
Field inheritance, a Declare OnChange rule named OutofStock at one level in the class structure
Description
may override (and so prevent execution of) a Declare OnChange rule named OutofStock at a
higher level in the class structure.

Rule resolution

About Declare OnChange rules

Viewing rule history
More about Declare OnChange rules

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...
Field Description
Select:

Choose — To cause all executing flows for a work item to be suspended. See
Suspend Work Object
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

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

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

About Declare OnChange rules

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

About Declare OnChange rules

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.

The following tabs are available on this form:

Triggers

For each Declare Trigger rule, the Pega Platform monitors database operations for objects of the Applies To
class (and concrete classes derived from that class). During database commit processing, forward chaining
processing may trigger — start execution of — the activity identified in this rule.
For example, a Declare Trigger rule can execute an activity each time an instance of Data-Party-Person
class is saved with a modified ZIP code (property Data-Party.pyPostalCode ). The activity might send an
email message to the sales representative whose territory includes the new address. Similarly, a Declare
Trigger rule can implement a form of logging or audit history for a class, recording the date, time, and other
facts.

Where referenced
No other rules explicitly reference Declare Trigger rules. After you save a Declare Trigger rule, it is run
immediately and as needed.

Access
Use the Application Explorer to access Declare Trigger rules that apply to work types in your application.
Use the Records Explorer to list all Declare Trigger rules available to you.

Category
Declare Trigger rules are instances of the Rule-Declare-Trigger class. They are part of the Decision
category.

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.

Declare Trigger form - Completing the Triggers tab

Complete this tab to identify those database operations that activate this trigger rule.

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

Calculating or validating values automatically

Declare Trigger 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 Trigger rule by selecting Declare Trigger from the Decision category.

Key parts:

A Declare Trigger 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 name for this trigger rule. Begin the name with a letter, and use only letters,
 numbers, the ampersand character, and hyphens.
Field Description
Identifier No other rules explicitly reference this Apply to value. However, because of normal class
inheritance, a Declare Trigger rule named NewGoldCard at one level in the class structure
may override (and so prevent execution of) a Declare Trigger rule named NewGoldCard at a
higher level in the class structure.

Rule resolution

About Declare Trigger rules

Viewing rule history
More about Declare Trigger rules

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

About Declare Trigger rules

Declare Trigger rules -
Viewing rule history
More about Declare Trigger rules

About Declare Trigger rules

Declare Trigger form - Completing the Triggers tab

Complete this tab to identify those database operations that activate this trigger rule.

Field Description

Select:

Saved
To cause this rule to execute when an instance in the class is saved (usually with the
Obj-Save method).
Deleted
To cause this rule to execute when an instance in this class is deleted (usually with the
Obj-Delete method).
Saved and...
Trigger To cause this rule to execute when an instance is saved and properties listed have
When an values different from the previous values.
Instance Committed Save
Is To cause the rule to execute when a Commit method occurs and the previous method
for the instance was Obj-Save. (Also, an Obj-Save method that executes with the
WriteNow option selected causes trigger rules with Committed Save to execute.)
Committed Delete
To cause the rule to execute when a Commit method occurs and the previous method
for the instance was Obj-Delete.

If you want processing to occur whether the instance is deleted or saved, create two
Declare Trigger rules, one for each situation.

...One of
These
Properties This area of the form appears only when you choose Saved and... for the previous field.
Was
Modified...

Optional. Enter a property reference. Identify a Single Value, Value List or Page List property that
resides on one of these pages:

The page defined by the Page Context field (on the Pages & Classes tab).
The top-level page that corresponds to the class defined in the Applies To key part of
this rule, or
Other pages defined in the Pages & Classes tab.

The second and third options are acceptable only when the Page Context field is blank. For
a reference to a property on the Applies To page, place a period before the property name.

Use a subscript to reference a scalar value of a Value List. Example:

Property
Vehicle(2) — a specified element, where Vehicle is a Value List property

To detect changes in any portion of a Value List or Page List property, follow the name with
empty parentheses. Examples:

Vehicle() — any element, where Vehicle is a Value List property

Child() — any element, where Child is a Page List property

The activity referenced in the Activity Name field can examine a system-created page
 Field named pyDeclarativeContext to determine which property or properties were modified.
Description

Optional. Identify a property of the same mode and type as the property in the Property
field on this row. This property can retain the current value of the changed property.
Copy Copying occurs only if the trigger activity runs, and after the trigger activity completes.
Value to
(optional) Copying makes the previous property value available to the second and subsequent
executions of this rule.

Condition

Optional. Select a when condition rule. When this field is not blank, the system evaluates
the when condition and performs the trigger operation only when the rule evaluates to true.
When
At runtime, the system uses the Applies To key part of this Declare Trigger rule as the
Applies To key part of the when condition rule.

Trigger
Activity

Identify the second key part — the Activity Name — of an activity to trigger when any of the
specified properties change. The system uses the Applies To key part of this Declare
Trigger rule as the Applies To key part of the activity.

Cick the Open icon to open the activity.

If Immediately is selected for the Execute field, only activities with the Activity Type of Trigger
appear in the SmartPrompt list for this field. Use of Trigger activities is recommended and
avoids a warning condition reported when you save this rule. You can type in the name of
an existing activity of another Activity Type, but the activity must conform to these
Name restrictions:

The activity cannot itself commit database transactions, because a triggered activity
runs during database commits.
Preconditions and transitions in the activity cannot use when condition rules and
cannot call functions.

Caution: Although your application can contain more than Trigger activities for one Applies
To class, you cannot control the order that they run when two or more are triggered. Create
activities that provide correct results when run in any order, and when run either
independently or simultaneously.

Select a value to determine how the activity runs:

Immediately — Runs the activity during forward chaining, before the commit completes.
Execute In Background on Copy — The activity executes in a new requestor, outside of the context of
forward chaining. The activity should include a Commit method. (This activity cannot
use Obj-Save with Write Now checked, but can use all other methods.

About Declare Trigger rules

About Declare Trigger rules

Declare Trigger rules -
Viewing rule history
More about Declare Trigger rules

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

About Declare Trigger rules
Declare Trigger rules -
Viewing rule history

About Declare Trigger rules

Defining conditions in the condition builder

Use the condition builder to define conditions for stages in your workflow or for propositions evaluated by a
proposition filter. You can save custom conditions to the condition library for future use.

Before you begin: Register the fields and when conditions that you want to use in your custom condition
as relevant records. For more information, see Adding a relevant record to a specified class in your
application.

1. For workflow stages, on the Validation tab, click Custom condition, and then click the Click to
 configure conditions icon.
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 first column, select a field or a when condition from the
list.
4. In the second column, select a comparator from the list.
5. In the third column, select a value.

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

6. Optional: Add conditions by clicking the Add a row icon.
7. Specify how these conditions relate to each other.
You can group conditions with AND or OR operators.
8. In the list in the upper-right corner, 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 mix of grouping by 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 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, so
you can identify them more easily.
9. Optional: To save the condition for future reuse, perform one of the following actions:
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 with 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 when rule is automatically registered 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

Calculating or validating values automatically

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 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

Designing applications for reuse and extension

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

Creating an activity

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.

Branching to another activity

Calling another activity
Methods and instructions by name
Queue instruction – run an activity asynchronously
Keystores

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.

Configuring steps in an activity

Keystores

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 Select to activate the transition. If this 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.

Configuring steps in an activity

Keystores

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.

Configuring steps in an activity

Keystores

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

Creating an activity

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.

Keystores

Creating an activity

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
activity in the RuleSets. Select this check box for all but those specific activities that
Require guests need to run.
authentication
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
 Field activities regardless of the Authenticate? value.
Description
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:

Select when 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).
Activity Type The Locate activity type is not supported. Existing activities
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.

Keystores
About Declare OnChange rules
About Declare Trigger rules
Activity form - how to create activities for flows

Creating an activity

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.

Creating an activity
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 Typeof Notify to identify activities in a Work- class that generate
correspondence.

Notify Correspondence generation can occur without any user interaction, or can capture user input in a
simple HTML form, or may start Microsoft Word on the user desktop.

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.
SwitchToWorkbasket
Route 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
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.

Keystores

Creating an activity

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.

Activity form - how to create activities for flows

Creating binary file rules

Enhance and customize your application by creating a binary file rule that in a form of a rule stores a
graphics file, such as an image, or other non-text files. Binary file rule type provides the security,
inheritance versioning, and deployment benefits of rule resolution to a file.

For example, you can upload your custom image to your Pega Platform environment so that you can use
the image in your application. You can upload different resources, such 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 new 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 of the
application server, enter webeb.
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 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 to store 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 .

Keystores
Viewing generated Java code of Access When rules

Designing applications for reuse and extension

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 Adding and configuring an
Image control.

Uploading custom font files

Designing applications for reuse and extension

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.

Designing applications for reuse and extension

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.

Creating a toggle

Optimizing application load time

You run a preflight optimization to reduce an application’s unnecessary static content and improve its
loading time.

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.

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. In the Access group list on the Basic tab, 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, you can select individual rules that will be included in—or excluded from—
the analysis of the application's design-time model.
e. Click Submit to save the optimization's configuration and start the analysis.

If you are running the access group's preflight optimization for the first time, or if you selected 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 to temporarily disable the optimization for
the access group and portal).

You might do this 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.

Designing applications for reuse and extension

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.

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

Optimizing application load time

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

Optimizing application load time

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

Optimizing application load time

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

Low-code application development

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.

Learning about 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.

Creating features

Ensure that your application supports capabilities that meets your specific business needs and
customer expectations, by creating features. When you create features, you communicate a design of
your application to stakeholders and development teams.

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.

Tracking feature-driven development

Create and manage stories to track the progress of your feature-driven development.

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.

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.

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.

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.

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

Engaging with stakeholders to define a Microjourney

Learning about 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

Adopting feature-driven development

Creating features
Ensure that your application supports capabilities that meets your specific business needs and customer
expectations, by creating features. When you create features, you communicate a design of your
application to stakeholders and development teams.

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 header of the Features section, click the Create icon.
4. In the Name field, enter text that uniquely identifies the feature.
5. 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.
6. Click Create.

What to do next: Extend the capability with additional capabilities by creating subfeatures. For more
information, see Creating subfeatures.

Deleting a feature

Adopting feature-driven development

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 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 header of the Features section, click the name of the feature that you want to supplement with
a subfeature.
4. In the Subfeatures section, click the Create icon.
5. In the Name field, enter text that uniquely identifies the subfeature.
6. 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.
 7. Click Create.

What to do next: Extend the subfeature with additional capabilities by creating additional nested
subfeatures. You can create four levels of subfeatures.

Creating features
Deleting a feature

Adopting feature-driven development

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 that you create.

Changing the level of a feature

Change the relative position of a feature in the feature hierarchy to support reuse and extension in
other applications.

Associating a rule with a feature

Document which rules implement a feature to improve the traceability and extensibility of your
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

Adopting feature-driven development

Reviewing application features

Review the current features in your application so that you can make informed decisions about the new
features that you create.

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 then review the subfeatures that extend your features.
5. In the Version column, review the application type to understand which features are unique to your
application and which features you inherit from other applications or versions.
Tip: To get the status of a feature, look at the progress bar in the Progress column or click the links
in this column to open the relevant stories, bugs, or feedback items in the Agile Workbench tool.
6. Click the name of a feature or subfeature, and then review the information that is displayed.
 Adopting feature-driven development

Changing the level of a feature

Change the relative position of a feature in the feature hierarchy to support reuse and extension in other
applications.

Before you begin: Ensure that you feature does not have any of the following characteristics:

Has dependencies from applications that build on your application

Has dependencies from later versions of your application

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 review the different levels in your feature hierarchy.
5. Drag a feature to a new position in the list to change its level and the level of its subfeatures.
6. In the header of Agile Workbench, click the More icon, and then click Application Profile.

Creating features
Creating subfeatures

Adopting feature-driven development

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.

a. On the Attachments menu, click Capture screen.

b. Drag the target pointer onto the screen area that relates to the feature
enhancement.
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.

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.
 Choices a. On the AttachmentsActions
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

Adopting feature-driven development

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.

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.
 Choices e. Click Submit.
Actions
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

Adopting feature-driven development

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

Adopting feature-driven development

Associating a rule with a feature

Document which rules implement a feature to improve the traceability and extensibility of your application.

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.
5. In the Name field, press the Down Arrow key, and then select the rule to associate with the feature.
Tip: To help you decide which rule to choose when there is more than one rule with the same name,
enter a class name in the Applies to field to narrow the list of results.

Result: Your application manages the links among features, rules, and work items as you develop your
application. When you create a rule by copying or specializing another rule, the links from the original rule
to work items are copied to the new rule. Features that are linked to the original rule are not updated with a
link to the new rule. When you delete, withdraw, or block a rule, the links to work items are removed. The
links from features to the rule are also removed.

Reviewing application features

Adopting feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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.

Integrating Agile Workbench with Pega Agile Studio

Setting your current work item
Adopting feature-driven development

Tracking 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

Tracking feature-driven development

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

Tracking 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

Tracking feature-driven development

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

Tracking feature-driven development

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
machine 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

Tracking feature-driven development

Importing story templates

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

Tracking feature-driven development

Populating story templates

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

Tracking feature-driven development

Importing story templates

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

Tracking feature-driven development

Importing story templates
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

Tracking feature-driven development

Importing story templates

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

Tracking 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

Setting your current work item

Tracking feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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

Adopting feature-driven development

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.

Managing application features

Creating a Microjourney for customer success

Adopting feature-driven development

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 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.

Engaging with stakeholders to define a Microjourney

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

Documenting your application

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

Documenting your application

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

Documenting your application

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

Documenting your application

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

Creating a guide for end users

Adding a task to a chapter in an application guide

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.

Adding supporting information to an application guide

Creating a guide for end users

Adding a chapter to an application guide
Adding supporting information to an application guide

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

 Creating a guide for end users
Adding a task to a chapter in an application guide
Adding an application guide to a portal

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

Adding supporting information to an application guide

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

Adding supporting information to an application guide

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

Adding supporting information to an application guide

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.

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

Adding supporting information to an application guide

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

Adding supporting information to an application guide

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

Creating an action set
Control form - Actions tab
Available actions and conditions

Adding supporting information to an application guide

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

Creating an action set
Control form - Actions tab
Available actions and conditions

Adding supporting information to an application guide

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

Creating a guide for end users

Adding supporting information to an application guide
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.

Keystores
Documenting your application

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

Describing features to end users

Associating content with a feature in a guided tour

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 a guide for end users

Describing features to end users

Creating content for a guided tour
Integrating a guided tour with your application

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

Describing features to end users

Associating content with a feature in a guided tour

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

Documenting your application

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

Creating guidance for developers

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

Creating guidance for developers

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 you are
accessing.

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.

The Regular Expression tester tool

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

Low-code application development

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.

Setting rule status and availability

Troubleshooting tools and techniques

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

Troubleshooting tools and techniques

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

Troubleshooting tools and techniques

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.

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

Troubleshooting tools and techniques

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

Application debugging using the Tracer tool

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

Tracer best practices

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

Application debugging using the Tracer tool

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

Configuring trace conditions

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
Displays a line at the start of each run of an Access Deny rule.
rules

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.

When Rules Displays a line at the start of every when condition evaluation, including preconditions
Start and transitions.
 When Rules
Events to Displays a line at the completion of every when condition evaluation, including
End Description
preconditions and transitions. If selected, Tracer output shows the results of all when
Trace
rule executions from all rulesets, regardless of your selected rulesets.

Tracing and capturing events

Configuring Tracer settings
Configuring trace conditions

Configuring Tracer settings

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.

 Label
Declare Description
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
selected.

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
Log-Message method
Tracing services

Configuring Tracer settings

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

Configuring Tracer settings

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

Configuring Tracer settings

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

Configuring Tracer settings

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
Java methods for dynamic system settings and application settings

Configuring Tracer settings

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

Adjusting the buffer size of the Tracer header

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

Configuring trace conditions

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

Configuring trace conditions

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

Configuring trace conditions

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

Configuring trace conditions

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

Application debugging using the Tracer tool

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. Note which ruleset the service rule belongs to.
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

Application debugging using the Tracer tool

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.

Tracing services

Tracing services

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

Application debugging using the Tracer tool

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.

 Column For a declarative rule or decision rule, indicates the start or end of a computation.
Description

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.

When you trace a database or cache operation , the Name and RuleSet columns are combined.
Name
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

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

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 you need to inspect, and then check whether these
elements behave in an expected way.

Adding a user page to the Clipboard

To add a user page to the clipboard, do the following.

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.

Track system utilization for a requestor session with Performance Analyzer

Page names and reserved pages
Application debugging using the Tracer tool

Troubleshooting tools and techniques

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.

Select to display the page's underlying XML. Use this command to see pz properties and other
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

Clipboard tool

Setting property values with the clipboard

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 you need to inspect, and then check whether these elements
behave in an expected way.

For example, to test a child case type before you finish creating its parent case type, you can provide data
that the child case type normally inherits from its parent. After you conduct your testing, you can debug
your application by providing different values, as necessary.

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 Run.
2. In the footer of App Studio, click Toggle runtime toolbar Clipboard . Result: The Pega Clipboard
window opens. The Thread panel lists pages in memory associated with the selected thread, such as
case types.
3. In the Thread panel, 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.
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

Clipboard tool

Adding a user page to the Clipboard

To add a user page to the clipboard, do the following.

1. Right-click User Pages in the left pane.

2. In the Add New Page dialog, in the Page Name field, enter the name of the page.
3. Optional. In the Page Class field, enter or select the class to which the page belongs.
4. Optional. In the Data Transform field, specify the data transform that supplies the initial values for
the user page. If the data transform sends parameter values to the user page, click Get Parameters
and enter the parameter values in the appropriate fields.
5. Click Submit.

Clipboard tool
Using the Clipboard tool
 Clipboard tool

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

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

Calling another activity

Clipboard tool

Log files tool

In the Log files tool you can view or download the current log files on the server node you are accessing.

Access this tool by clicking Configure System Operations Logs .

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 the Pega Community article Performance alerts, security
alerts, and AES.
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.

Viewing logs

View the log files to see the completion status for operations. The log files match the current operator
ID for all the sessions on the server node.

Downloading log files

You can save your log files to view them later.

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.

Troubleshooting tools and techniques

Viewing logs
View the log files to see the completion status for operations. The log files match the current operator ID for
all the sessions on the server node.

1. Click Configure System Operations Logs .

2. Click Log Files.
3. 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: Change or remove the log filters, or the lines displayed.
Lines Per Page – The maximum number of lines is 200.
Number of Pages Presented – The maximum number of pages to present is 20.
Filter by – Remove the default value to display the entire file or enter another operator ID.
5. Click Apply to apply the new filter and display options.

Result: Note: To view only alerts from your own requestor session, select Alerts from the Dev Studio
toolbar.

Log files tool

Downloading log files
Viewing log files in an external log viewer
My Alerts display

Log files tool

Downloading log files

You can save your log files to view them later.

1. Click Configure System Operations Logs .

2. Click Log Files.
3. Click:
text - to download a log as a text file, with .txt as the file type.
zip - to download a log as a .zip file.
4. Enter the authentication information for your application server and click Log in.
5. Select where you want to save your file, and click Save.

Log files tool

Viewing logs

Log files tool

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.

Viewing logs

Log files tool

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

Log files tool

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.

Log files tool

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.

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.

Log files tool

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

Logging Level Settings tool

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 .

Logging Level Settings tool

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

Log files tool

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 files tool

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

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.

Log files tool

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.

Troubleshooting tools and techniques

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

My Alerts display

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

My Alerts display

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

My Alerts display

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

My Alerts display

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.

Requestor A - requestor is being used by an application

 I
Column ID
Field B - batch requestor used by agent processing
Description
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.

Rule
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
 Column Step page
Field Description
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 Pega stack The Pega stack at the time of the alert.

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

My Alerts display

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.

Troubleshooting tools and techniques

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.

Troubleshooting tools and techniques

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.
2. On the Service tab of the Connector rule form, click the Simulations button to access a form.
3. To enable simulation, select either the Global or UserSession options. Complete the form and click
Apply Changes.
4. 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 rule identified by the previous fields in this row.

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-Connectors category

Troubleshooting tools and techniques

The Regular Expression tester tool

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
 Field Select to cause two characters toDescription
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.

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

Troubleshooting tools and techniques

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

Understanding the Date, Time of Day, and DateTime property types.

Troubleshooting tools and techniques

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.

Application Validation mode ruleset

An Application Validation (AV) mode ruleset can reference all rules in a ruleset that is defined in the
same application or a ruleset that belongs to any built-on application.

Troubleshooting tools and techniques

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 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

About the bulk Revalidate and Save tool

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.

RuleSet Optional. If you chose a rule type, you 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

About the bulk Revalidate and Save tool

Application Validation mode ruleset

An Application Validation (AV) mode ruleset can reference all rules in a ruleset that is defined in the same
application or a ruleset that belongs to any built-on application.

Example using only AV mode

In this example, it is assumed that AV mode rulesets are used. Each shaded or unshaded cell represents an
application and each name represents a ruleset. With AV mode, you have the ability to call rules both
above and below the designated ruleset.

Ruleset Mode

LoanPricing Can call all other rulesets listed.

LoanUnderwriting Can call all other rulesets listed.

Can call LoanUnderwritingFW but not shaded

LoanPricingFW
rulesets.

LoanUnderwritingFW Can call LoanPricingFW but not shaded rulesets.

Example using mixed AV and RV modes

This example uses a mixture of AV mode and Rule Validation (RV) mode. A ruleset name with brackets
indicates a RV mode ruleset with its respective prerequisite. With RV mode, you are unable to call an AV
mode ruleset not listed in the prerequisites.

Name Mode

LoanPricing Can call all other rulesets listed.

LoanUnderwriting Can call rules in all other rulesets including LoanPricing.

Can call rules in MyCo but not in LoanUnderwriting, LoanPricing, LoanPricingFW,

MyCoPL [MyCo]
or LoanUnderwritingFW.

LoanPricingFW Cannot call rules in MyCoPL, LoanUnderwriting, or LoanPricing.

LoanUnderwritingFW Cannot call rules in MyCoPL, LoanUnderwriting, or LoanPricing.

MyCo[PRPC] Cannot call rules in MyCoPL, LoanUnderwriting, or LoanPricing.

Note: As a best practice for design, your unlocked AV mode rulesets should belong to one Rule-Application,
but can still belong to more than one version. This prevents AV mode rulesets from referring to rules that
may not exist in all applications that the ruleset is contained in.

Alternately, rulesets should be refactored into applications that are included as built-on applications.

It is recommended that new rulesets use AV mode. However, if refactoring does not work, then the
rulesetcan be set to RV mode.

Versions
Versioning in AV mode works similarly to how it does when using RV mode. Within a given ruleset name,
you cannot call rules in a higher ruleset version. For example, rules in App:01-01-01 cannot reference rules
in App:01-01-03 at design time. For versions across different ruleset names, the standard AV mode logic is
applied.

Branches
A branched ruleset using AV mode can access all rulesets in an application, including other rulesets in the
same branch and any other branches included in the same application definition. This means that all
branches within a given application definition can refer to each other. Rules in non-branched rulesets
cannot reference rules in any branch.

The validation mode for a branch ruleset, set as AV mode by default, can be changed. It is recommended
that validation mode be kept the same as the mode used by the base ruleset, but this is optional.

A branched ruleset is initially set to the same validation mode as the non-branched ruleset. If the validation
mode of the branched and non-branched rulesets do not match, a warning displays, because there is the
potential for a conflict upon merging. Best practice recommends using the same validation mode for both
the branched and non-branched ruleset instances for the same ruleset name.

Mobile and local rulesets

Mobile and local rulesets have their own ruleset validation mode. If set to AV mode, a mobile or local
ruleset can refer to all rules in the application (or built-ons). An application ruleset cannot explicitly refer to
local or mobile rulesets unless they are added to the application.

Note: Adding local or mobile rulesets to the base application ruleset is not recommended because non-
local or non-mobile rulesets could call into the local/mobile rulesets.

Production rulesets
Production rulesets get placed on top of the stack and can reference application rulesets, although
application rules cannot directly reference a production ruleset. A non-production version of the rule must
exist for validation.

Component/shared rulesets
These ruleset types cannot be set to AV mode.

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 .

Troubleshooting tools and techniques

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
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.
 Field Click to display the Application Lock and Roll window where you can review, lock current
Description
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.
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.

Application Structure landing page

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

Application Structure landing page

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

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
of users that reference that access group, and so have that level of access into the
 Group
Field application.
Description
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

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

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. 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

Application Structure landing page