Page |1

Report Definition in Pega

Published December 25, 2017 by Premkumar G
54

Introduction

In this post, we will see in detail about report definition rule, how to create a new RD
and its usage.

 I love the term ‘Data’. Every business process requires some data. Think of any
organization – bank, finance. They collect the data and use the data for their
business processes.
 Every BPM application requires some data for processing.

Let’s take the usual example – Amazon.

 They need the customer data, product data, vendor data, courier
transportation data etc.
 They store these data in some database (Oracle, MySQL, Postgres, etc) and
use the data when required.

Now how can Amazon application talk with the database. They need some language
right?!

Any application can talk with the database using Structured Query Language (SQL)

Pega stores the permanent data in database tables and temporary data in memory.

So Pega talk to the database using SQL. There is a rule type Connect-SQL to support
this.

So what is the use of report definition here?

 I would say report definition is a User-friendly version of connect-sql ruleJ

Important note: Report definitions can only be used to browse the record from the
database table. It cannot be used to alter / update / delete the records.

What is a report definition rule?

 Page |2

 A report definition rule generates SQL query to retrieve data from the
database tables and can generate HTML to display the results.
 Reports definition supports chart and can be used in dashboard reports.
 Report definition can retrieve data from two or more tables.
 Report definition supports parameter and can be rendered dynamically.

Where can we refer a report definition rule?

a) Data pages – as a source to fetch multiple results. ( page list).

b) Used in many UI controls – repeating grid, list, autocomplete
c) Called from activity – Rule-Obj-ReportDefinition.pxRetrieveReportData

How to create a new report definition rule?

Before continuing let me explain my requirement.

Scenario – I need to fetch the details – pyID, CustomerName and

PhoneNumber related to Case S-1.

Select pyID,customername,phonenumber from pc_pks_myknowpega.com where

pyid=S-1.

Below is my SQL query.

Let’s see how we can achieve the same using report definition rule 🙂

 Determine which table we need to browse

 We know that all concrete classes in Pega are mapped to database tables. We
need to check which instances we need to browse and from which table.

Here, we need to browse the Sales class instances, Let’s open the class and check to
what table it points to?

It is pointing to pc_PKS_myKnowPega table. ( equired table).

So we can create a report definition rule on the Sales class instance.

Step 1: Records -> Reports ->new

 Page |3

Applies to – Decides on which instances we are going to report.

Here in this demo, I am going to report on all the sales cases in the application. So
my applies to class is ‘PKS-MyKnowPega-Work-Sales’

You completed this part 🙂

 Determine what are the columns you need to report

There are 5 Important tabs in a report definition rule.

a) Query tab
b) Chart tab
c) Report Viewer
d) Data Access
e) Parameters

Step 1: Query tab – Edit columns.

In this block, you can specify an array of columns you need to fetch from the
database table and can also decide the presentation for each column.

Column Source – here you got 2 options.

a) Use single value property – You can either use optimized or un-optimized
columns ( affects performance)
b) Use calculation builder to use a function template and format the column value.

I will make a short post on, how to create a SQL function and use one 🙂

Now save it and run the report definition rule.

You get all three sales cases from the database table.

The other 3 columns in the ‘Edit Column’ block, determines the UI representation of
the results.
 Page |4

a) Summarize

-Count, Count distinct, Max, Min, Sum, Avg .

This list varies based on the property type. Obviously for the property pyID of type
‘text’, we don’t need the Sum and Average summarization 🙂

We will see in later about the differences between List reports and summary reports.

b) Sort type – It can be blank, Lowest to highest (ascending) and Highest to lowest
(descending).

c) Sort Order – With in the sort type you can determine the priority of sort order. It
can be 1-N.

 Imagine I am fetching the country and state in the search results. I gave
country as Sort order 1 and State as sort order 2.

You can see in the below picture, sorting is first applied to country and then within
the country sorting is applied for states.

You got a Settings icon on each row. Let’s check it. There are few additional options
available.

Column width – You can determine the Column width in px or % ( dropdown option)
Column format – You can determine presentation of the column values.

Hide column – You also got an option to hide column.

Filtering option –

o Auto – Displays both list and search range.

o List only – No search
o Search range – No lists. Only search option.

When you select summarize, you get different additional options.

 Page |5

You get an option to display values across columns. Now you know, how to include
the columns and format the results.

 Determine and configure the filter conditions.

Condition – you can specify the condition logic label. If there are more than one
condition in where clause, then you can differentiate them using labels.

Caption – Description on the filter condition displayed in the report viewer. We will
see more in detail later in this post.

Column source – You can specify the column name on which you are going to apply
the filter condition. You can also use calculation builder to use some functions.

Relationship –

You can make use of any arithmetic operations J

Value – you got variety of options.

a) You can either hardcode the value or get the parameterised value dynamically.
b) Select Value – You can click on the link to select the available values ( Internal
query executed to get all the data).

This list all the available pyID values for the sales instances. You can select one.

c) Calculation builder – you can also make use of the function to render the
calculated values.
d) Other Filter Options.

Report Viewer Changes –

What is report viewer?

When you run a data transform, you get a window to display the results.
 Page |6

a) Allow any changes – Default, we can update both the column and
its values
b) Allow changes to value only – We can update only the column values
c) Read only, allow no change – We cannot update the filter conditions
d) Field not visible in Viewer – Filter section is not visible

We will test

Use Null if empty –

Imagine we have a where condition where the value is passed dynamically. Say the
filter condition is pyID=Param.pyID

If Use Null if empty – True – then the where condition will be .pyID=””
If Use Null if empty – False – then the entire where condition is ignored.

Ignore Case – You can also ignore the case ( case sensitive or not) for the values.

Filter conditions to Apply –

If you have more than one filter rows, then you can use the logical operators to
satisfy the requirement.

Update: for a summary report, you get an option to use filter condition after
aggregation

Here you can make use of aggregate column as filtering option.

Filter Caption conditions –

a) Allow caption to entire condition

b) Allow caption to left side of condition

Allow caption to entire condition – Instead of displaying pyID=”S-1” as a filter

condition, we can use a caption to give some meaningful description.

I am using FirstCase as a caption to Condition A.

 Page |7

Run the report, you can see the caption in the filter conditions.

Allow caption to left side of condition – You can allow the caption to only left side of
condition.
Like FirstCase=S-1

Remove duplicate rows –

True -Removes duplicate rows in the search results.

You can see in the below picture that S-1 & S-3 contains same customer name and
phone number.

Step 1: Add only customername and phonenumber as select columns. For testing
remove all the filter conditions

Step 2: check the Remove duplicate rows checkbox.

Step 3: Run the report definition.

You can see only 2 reports, because a duplicate row is removed.

Ranking –

You can rank the results and filter and display only few results.

o You can either select Top ranked (highest value) or bottom ranked (lowest
value).
o You can specify the number of rows to retrieve.

You can use either OverAll – To use all the search results in ranking; For Each
Group – Ranking within the group

Based on – You can specify any field to rank.

Scenario – Here I need to fetch and display recently created Sales case.

My ranking criteria will be Top ranked = Highest values = maximum created date
 Page |8

Run the report.

You can see it returned the recently created sales case S-3 🙂

Scenario for ‘For each group’

Scenario – You need to fetch and display the operators who are getting the highest
salary in their department ( Sales, Service)

You can enable ‘For each group’ Also you need to do some configuration in Report
viewer tab.

Check group results and decide what are the columns can be group headings.

In the above picture, I selected 1 – 1, So the sort order = 1 column will be the column
heading.

Run the report, by select ‘For each group’ in ranking.

 You can see ranking is done based on the phone number grouping.
 S-1 and S-3 have same phone number, but the highest ranked case is S-3
(recently created) J

End of first tab.

Chart tab, Report Viewer – We will see more in detail in separate post.

Data access

 Use this tab to control all the data configuration settings.

I am making a separate post on Class Joins, Declarative Index Joins, Associations, Sub
reports.

What are the other data configuration options?

 Page |9

Maximum number of rows to retrieve – This is disabled, because paging I enabled in

the report viewer tab. If you need to set maximum record count, then you need to
disable paging and set the value.

Maximum elapsed time in seconds – You can specify the maximum number of
seconds, the report is allowed to run. If does not return the results in the specified
time, then the run is interrupted.

Maximum number of rows for export – Specify the maximum number of rows to
export.

Maximum elapsed time in seconds for export – You can specify the maximum
number of seconds the export process is allowed to run.

You can see the default configuration values above.

Report on descendant class instances –

What is a descendant class?

 Say my class is PKS-Myknowpega-Work-Sales, then I can say PKS-

Myknowpega-Work-Sales-Fashion is a descendant class to sales class.

On selecting this option, I can fetch all the descendant class instances too.

Include Implementation class only – It used only Implementation layer class

mapping.

Include all descendant classes – this is default select and include all instances
irrespective of layering.

Use alternate database – You can use an alternate database table to report on.

Note: Alternate database table details are specified in the database table instance
 P a g e | 10

Row Key settings –

On selecting this option, the row key (pzInskey) will be default added in the select
columns.

Security –

You can specify a privilege rule. The operators with the specified privilege can only
run the report!

Parameters tab

This is the most commonly used tab.

Introducing parameters can support reusability. At run time we can pass different
values to the parameter and get the result.

Step 1: Add a parameter ID

Step 2: In the Query tab – filter conditions add the Parameter value as condition
value.

Step 3: Only for testing, set the parameter value to S-1

Step 4: Run the report definition rule.

You can see the results. You can pass this parameter dynamically at run time.

How to debug a report definition rule?

1. After the report definition rule is run, You can check a page
‘pyReportContentPage’ in the clipboard.

You can also see the pxResults pagelist to see the results content.

2. Run the tracer and capture the query.

Let me end this post 🙂

 P a g e | 11

Report Definition – Class join, Declare Index join,

Associations and Sub reports
Published December 25, 2017 by Premkumar G
44

Introduction

In the previous post, we saw a simple example to fetch the data from a single table.

For more details, please visit the below link

Report Definition in Pega

However there may be situations, where we need data from more than one table.

Can Report definition support this? Yes it is 🙂

 In SQL, you might have come across the terms – INNER join, Left OUTER Join,
Right OUTER Join.

Pega supports the same joins in the report definition rule.

 In facebook, you know a term ‘Friend of a Friend’. A friend of friend can see
some private details this, that!!Here you need some common friend, to view
few details.

Like the same, if you need details from 2 tables, then you need some common
column – This is where the join takes place 🙂

What is Inner join, Left outer join, Right outer join?

I have two tables – States table and Countries table

 Here, you can see Country code is a friend of friend to both the tables.
 I need to fetch 4 columns – StateID, State Name, Country Code (States table)
and Country Name (Countries table)

Left table – States; Right table – Countries

 P a g e | 12

INNER Join – Also called as simple join.

The below picture shows you the result of Inner join

It takes out rows which are common(intersection) in both the tables by Country
Code. Leaving out Country code 04 and 05

Left Outer Join – Includes all the rows in the left table and uses only data from the
right table.

You can see all 5 entries are in the results table. Right tables are just used to get the
data.

Right Outer Join – Includes all the rows in the right table and use only data in the left
table.

You can see all 4 countries are listed.

Let’ Jump to our Pega.

Requirement – I got a requirement to display the sales details and the assignment
details.

Here I need to join two tables – Work table and Assign-Worklist table.

Let’s see the records in both the table.

Sales table – You can see 4 entries.

Worklist table – You can see 2 entries

Here pzInsKey in work table and pxRefObjectKey in worklist table, both points to
case Key and can be considered friend of friend. You can join using those columns

Step 1: Open the Report definition rule – Data access tab

Step 2: Fill out the class joins block.

 P a g e | 13

Already the report definition is reporting on sales class (applies to).

Prefix – Specify a prefix for the joining class

Class name – Join class name.

Type –

a) Only include matching rows – Inner join

b) Include all rows in this class (Applies to class) – Left outer join

c) Include all rows in joined class (worklist) – Right outer join

Edit conditions –

Column refers to – Sales work table column

Value refers to – Assign-Worklist table column

You can add one or more rows as filtering conditions. Prefix A is used to identify the
joined class columns.

Note: You can also add more than one class joins in a report definition rule.
Step 3: Go to Query tab and add the A.pxAssignedOperatorID column

Step 4: Run the rule and test it.

You can see the inner join results J

Left Outer join

Step 1: update the class join to type

 P a g e | 14

Step 2: save and run the rule.

 You can see all rows are included from the Sales class with data only copied
from the joined class.
 There are no entries for S-1 and S-3, so no Operator ID.

Right Outer join

Step 1: Update type to ‘include all rows in joined class’

Step 2: save and run the rule.

You can see all rows (2) in the joined class are included and the other columns are
just filled from the left table.

Based on your requirement, use it wisely 🙂

Declarative index Joins

Declarative index joins is similar to class join with the exception that instead of class
name, we specify declare index name J

Associations

What is Association rule?

 It is very simple. If you find, you join two class instances frequently in report
definition, you can create an association rule.
 Association rule explicitly defines the Join condition between two classes.
 Pega provides many standard association rules. You can also create one.

How to create a new association rule?

Step 1: Records ->Sysadmin -> New

Step 2: Specify the configuration points.

 P a g e | 15

Note: Prefix should be same as the association rule name.

Step 3: Refresh the report definition

Still no association rule?????? Cool.

You need to refer a property in the query tab.

Step 4: Add a column using association prefix.

Step 5: Now check the data access tab.

You can see the association rule added.

Step 6: run the report and check the Inner JOIN results.

Association supports reusability in class joins 🙂

Sub reports

What is a Sub report?

 Sub report is a name we refer to report definition rule, when it is used in

another report definition rule.
 To satisfy complex requirements and use the results of the existing report
definition, we use sub reports.

Let me explain you with an example.

Requirement – I have a simple requirement, to get the list of operators who don’t
have any assignments ( Assign-Worklist) entry.

My design choice is
 P a g e | 16

1. Create a main report definition rule on operators class

2. Create another report definition (sub report) on worklist class.
3. Use the worklist results to filter out the operators

Step 1: create a new report definition rule in ‘Data-Admin-Operator-ID’ class.

Note: I used organization to filter out default pega operators.

Step 2: run the report definition and check the operators list.

Step 3: Create another report definition rule in Assign-Worklist class (sub report)

Step 4: run the report definition to get the list of operators who have assignment in
their worklist.

There are 2 assignments and both are in my name J

Note: This is the ideal candidate to use remove duplicate rows option.

Step 5: Now go to ‘GetOperatorsList’ report definition and add the sub report.

Step 6: configuration is the key part here. Click on configure option

You can select number of rows returned from the sub report – More than 1 row

Where will you use this sub report?

I selected right side of filter.

 You can specify filter conditions for the sub report results.
 You have an addition type option – Do not match rows.

Note: If you don’t use any join condition, you can choose – Do not match rows (I
choose this)
 P a g e | 17

Ignore filter conditions in sub report – We can also ignore the filter condition in sub
reports.

Local names for sub-report columns

 You can specify some local names for sub report columns.
 You can also specify the parameters for the sub reports. If you use the same
parameter value in both reports, you can check the Auto-populate option.

Step 7: Now add the filter condition in the main report.

Step 8: save and run the rule

My Name is gone 🙂

Please follow the below link to know more about when and how to use sub reports.

https://pdn.pega.com/when-and-how-use-sub-reports-report-definition-reports

Hope you enjoyed this post 🙂

 P a g e | 18

Report Definition – List reports, summary reports, Report

viewer, Report editor
Published December 25, 2017 by Premkumar G
14

Introduction

In this post we will see the types of reports and then the capabilities in report viewer
and report editor

For report definition basics, please visit the below link

Report Definition in Pega

To know about Class joins, Declare index joins, Associations and Sub reports, please
visit the below link

Report Definition – Class join, Declare Index join, Associations and Sub
reports

What are the types of reports?

There are two type of reports Pega supports.

1. List Reports
2. Summary reports.

What is List report?

 This is the normal standard table format report.

Scenario– Get a list of sales instances.

 You get a list of items here.

 List report makes use of single value columns and not aggregate calculation
are involved.

What is summary report?

 P a g e | 19

 This helps in displaying count, total, average.

 Summary report supports charting.

List report can be converted to a summary report by updating the summarize column
in Query tab.

I am going to display a summary report on count of cases in different status.

From the list report, we can say

New =2 ; Open =1; Resolved – Completed = 1.

Let’s create a summary report to display the results.

 I made an aggregate calculation on pyID row and pyStatusWork as sort order

1.
 The sort order determines the result grouping. ( you can remove phone
number – no use)

Save and run the report.

You can see the grouping and the case count 🙂

 Summary report supports Charts. Charts serve to display the report results in
pictorial representation.
 Once you enabled summarize column in any row, you get the chart tab
enabled for selection.

How to include chart?

Step 1: click on include chart icon in the chart tab

You get the chart editor.

 You can select a chart type from different types available. I selected bar type
 You also have some option to set legend and glider option.
 P a g e | 20

 You can drag and drop the columns in the drop zone.

Aggregate colmn – count(pyID)

Group by column – pyStatusWork.

 You can also drop customer name column over the chart.

Save and run the rule.

 You can see the report is rendered in chart.

 This can be used in manager dashboard reports.

Report Viewer

Report viewer is the window which displays the report result, when you run it.

The configuration of report viewer is set in the report definition rule – Report viewer
tab

Report header

Note: You can customize the header by overriding pyReportEditorHeader section

 You can configure, the report title and header display

Do not scroll header – You can freeze the header, when the results are large and
involves vertical scrolling

Display filters using section –

You can also use custom filters using section.

I have a requirement to have a filter section supports filtering based on

pxCreateDateTime.

Step 1: Pega provides a sample section that is used to filter the results based on
range.
 P a g e | 21

The property referred are

Start : pyRuleStarts ; End : pyRuleEnds.

Note: You can create a similar one on your own 🙂

Step 2: Specify the section name and prefix

Display custom section inline – displays the filter section inline in report viewer. It
not checked, it is visible in the modal dialog on click on filter section.

Step 3: Use the filter in the query tab. CustomFilter.pyRuleStarts / pyRuleEnds

Step 4: Save and run the rule.

Report body

 Display actual data while editing report – While in report editor, you can see
the actual data
 Display rows in custom section – You can display rows in a custom section

Grouping –

 We can group the results and display values as group headings.

 Records are grouped based on the sort order specified in the query tab.

You can see the records are grouped based on work status (Sort order 1)

User actions – These configurations determine what are the actions, user can
perform on the report viewer.

Enable actions – determine what are the options to be available in the Other actions
option.

Enable Paging – on clicking options, you get a modal dialog to configure.

 P a g e | 22

Enable smart info – if required, you can show some additional information on each
row.

Note: You make use of an activity that accepts pzInskey as parameter and returns the
section content.

Report Editor

 By default developer and manager role have the required privilege to edit
report from the report browser.

Click on the edit report.

 You can drag and drop the property either in the filtering area or results grid.

 Click on the column heading menu. You can take action on the column
heading

 In the header area you can save your changes.

Let me how you a small demo, how to add a new column – pxCreateDateTime

Step 1: From the data explorer, select the pxCreateDateTime and drag and drop to a
new column.

Step 2: You can select a data interval

Step 3: In the Header, click on done editing.

Step 4: Go to report definition and refresh the rule.

You can see a new row is added with the function we selected:)

You can see how things are made easy.

Finally I am ending my 2 day marathon blogging 🙂 See ya soon in my next

post! Happy Christmas!!!
 P a g e | 23

Configure reports in User portal

Published January 8, 2018 by Premkumar G
32

Introduction

Welcome to my 50th post!!

In this post, we will see more in details about how to create reports and
personalize from user portal.

 In earlier versions, normally developers create the reports for the

business users. Developer use, report definition rules to create reports
and UI rules to display them in the user portal.
 In the recent releases, you might have come across many features made
configurable to business users. The most important one is reporting!!

Business users can themselves create reports from the user portal. Obviously
at back end, report definition rules are created.

How can you create a rule at the back end?

Just think broader. Pega rules are mostly configurable.

To create a new rule, you need values for some configuration points.

Take report definition as example, what are the major configuration points
required to create a new report definition rule?

1. Report name
2. Report class
3. Reporting ruleset
4. Columns to include (format)
5. Filter conditions

 Normally as a developer, you can configure these details in the report

definition rule form. So what about business users, who have( or don’t
have) only minimal knowledge on report definition rule form.
 Pega provides a template to the business users, to fill the require details
:).
 P a g e | 24

On saving, Pega creates a report definition at the back end. Is it a radical

automation :D. Yes it is

 Filling the template is always easy for any business people. Job done.

How to create a new report from the user portal?

Step 1: Login designer studio and launch the manager portal.

Why manager portal? – default manager portal provides reports in the

dashboard left navigation.

Step 2: On the dashboard left panel, click on the ‘Reports’

You get the recent reports column in the work area and categories in the right
panel.

Step 3: Go to right panel

Here you got 2 buttons.

1. Add report
2. Add category.

You can also find the list of categories available.

What is private category and public category?

 You can create a new report under a category.

 Categories help in grouping the reports. For example Sales reports,
service reports etc.
 So whenever you create a new report, you can have it in private category
and do all the changes. It is more or less like having a private checkout
and doing all the changes. It will not be shown to other Operators.
 P a g e | 25

 Once you complete your changes. You can publish your report from
private to public category.You can also directly publish it to public
category.

Note: Public category include – standard and shared category. More

details on category, we will see at the end of this post.

Note: System automatically creates a new private category My Reports,

whenever you create a new report. We will see about it soon.

So, here I am creating a new public category. Click on Add category and
specify the category name and type.

 Click submit. You can see a new public category with 0 reports.

Now you may get a question, how this is stored in Pega?!

Pega creates a new rule under category rule type J. We will see more in detail
later in this post.

Step 4: Click on Add report.

Error!!. you must have a local ruleset available to create a

category/report

 This is a valid error. As I mentioned before, we will be creating a report

definition rule at the backend.
 We know every rule should we within a ruleset and to create one, we
need an open ruleset version.

So, in this scenario, we need an open ruleset version 🙂

What are the pre requisites required to enable report creation

from user portal?

1. Separate reporting ruleset

Step 1: create a new ruleset Records -> Ruleset -> New

I am creating a ruleset as “PKSReporting” – <Org Name>Reporting.

 P a g e | 26

Step 2: Uncheck ‘Use checkout’ option.

Why do you do this?

 Usually in Production environment, we don’t create any new rules. So,

‘Allow rule checkout’ will be disabled in all users operator ID for security
reasons.

 So, to enable users to create report definition in particular ruleset, we

have to disable ‘Use checkout’ option.

Note: Usually in all production rulesets, use checkout option will be

disabled.

 Here multiple users can update the rule at the same time without any
lock.

2. Specify the reporting ruleset in the Production rulesets array in

the application rule

Step 1: Open the current application.

Step 2: specify the reporting ruleset under Advanced->Production rulesets.

Save the application rule.

3. Specify the reporting ruleset in Operator Access group

 We need to specify the reporting ruleset as a destination ruleset in

design time configuration.

Since, I am using my own operator ID, I am updating the my access group.

Note: Usually you update the users access group who can create reports in
production

Step 1: Open the access group -> Advanced

 P a g e | 27

Step 2: specify the reporting ruleset under design time configuration.

Step 3: When you save the instance, you may get this error.

 This is because, you need to specify the reporting ruleset in the product
rulesets array in the access group form.

All perquisites are set :). Let’s continue creating the new report.

Step 5: Go to the user portal and add a report.

Now you don’t have the error.

Here, you can specify two things.

a) Case type –

Technically – determines the Applies to class for the report definition.

Functionally – determines on which case instances, we need to report on.

b) Report type – List / Summary

Here, I am choosing Case type – Sales & Report type – List. Click submit

Step 6: you get the report editor window.

Hope you know, how to add columns and filter using report editor.

You can also visit the below link for more details.

Report Definition – List reports, summary reports, Report viewer, Report editor

Step 7: I am removing all the filters and adding case ID & Customer name as
the display columns.

 After adding columns and filter options, click done editing.

 You get a modal dialog to enter the report name and save the report
under either private or public category.
 P a g e | 28

 You can see Pega created a new private category ‘My Reports’.
 I am going to save the report under private category.

Click on the private category. You can see the report ‘Sales Case details’.

What are the actions you can perform on reports and categories?

a) On Categories

 Click on the settings icon near the categories. You can edit the category
name.

b) On Reports

 Click on the settings icon, you got five options.

 Edit – You can edit the report title and description.

 Move – You can move the reports to another category within private or
public category. Source report gets removed.
 Copy – You can copy the report to another category between private
and public categories. Source report is not removed.

I am copying this report into Sales reports public category.

You can see the report got copied in Sales Reports.

 Delete – You can delete the report.

Note: Deleting the reports, make the corresponding rule blocked.

 Schedule – You have an option to schedule the report.

Task Scheduling – You have few options to schedule the report delivery (
time and error hadling).

Task Output Processing – You can attach the report in PDF or excel. You
can select the operators you need to send notification. You can either attach it
in the email or send a link to download.

You also have an option to configure notification message. Click on the button.
 P a g e | 29

 You get fields to enter the email subject and message. Click submit.

You can see the report is scheduled and subscribed.

Now let’s see what really happens at the back end 🙂

What are the rules and data instances support reporting?

Step 1: Open the reporting ruleset.

Step 2: Click on the All rules count link.

You can see three types of rules got created.

1. Category
2. Shortcut
3. Report definition

First let’s see the report definition rule .

Report Definition – Click and open the rule.

 Now you open the same report from user portal. Click on edit report
and remove the pylabel column.

 Save the report. Now come to designer studio, and refresh the report
definition.

 You can see the pyLabel column removed automatically. So the changes
you do from the portal will get reflected in that report definition.

Note: You can also perform the vice versa. Updating the report definition
rule directly, can reflect the changes when viewed from the user portal.

Category – There are 2 new categories created. One private category and one
public category.

 Click and open the Sales report category.

 P a g e | 30

Public category can be owned by two ways.

 ALL – Standard. ( Accessed by all people)

 <Access group> – Shared ( Accessed by specific people under the
access group)

What is the difference between standard and shared categories?

 Standard categories can be accessed by everyone. Shared categories can

be accessed only by particular access group.
 Pega creates the standard category by default, when the user has
enabled checkout in the operator rule form. Shared category is created,
when the same is not enabled in the operator rule form.
 Standard categories are denoted by owner type ‘S’ while shared
categories are denoted by ‘A’

Note: private categories are denoted by ‘P’

Let’s test this.

Step 1: Use any manager operator ID and uncheck the Allow rule checkout
option.

Note: Also make sure the manager access group is specified with reporting
ruleset.

Step 2: Login to manager operator ID and create a new public category –

TestShared.

Step 3: Now check the category rule in the reporting ruleset.

 You can see Owner type ‘A’ shared and Owner as Managers access group
🙂

You can also create a new category – Records -> Reports -> Category
 P a g e | 31

You can specify the Owner type and owner name!

Shortcut

Click and open any shortcut rule in the reporting ruleset.

You can see the ID highlighted

MyReports – category name; P – owner type; Prem – Owner name

(private); Sales case details – rule name.

 You can see each shortcut points to a report definition rule.

 Just imagine shortcut as a pointer to the report inside category. If you
copy the report to new category, then a new short cut will be created.

You can also create a new short cut rule via Records ->Reports -> short cut

What are the instances that support scheduling reports?

Make sure you schedule a report as discussed previously.

a) Scheduled task instance – Pega creates a new instance under ‘Pega-

ScheduledTask-Reporting’.

You can open by two ways.

1. You can see those instances by navigating Designer studio -> Reporting
-> Components -> Scheduled Tasks

 You can also click on the task name to see the contents. Case id is PX-
ST-3

 You may have to move this scheduled task instance to higher

environment.
 In such case, you can include the instance pzInskey in the product rule
and move it to higher environment.
 P a g e | 32

2. In the app explorer, you can open the class ‘Pega-ScheduledTask-Reporting’

and click on it to see the instances.

 You can click and open the instance and get the pzInsKey.

Include the same in product rule and move it to higher environment.

 So here a case is created, but how the notification is sent periodically.

 On hearing periodically, you may remember agent processing 🙂

b) Queue instance

You can open the class ‘System-Queue-ScheduledTask’ and get the queue
items.

You can open the instance and get the pzInsKey. The same can be deployed to
higher environments.

We are at the end of Reporting 🙂 Hope you liked my 50th post !!+

It is time to enter Case Management !! See ya soon. Happy New Year !!

 P a g e | 33

Schedule reports in Pega

Published December 12, 2019 by Premkumar G
0

Introduction

In this post, we will see how to schedule and subscribe any reports from
Pega.

Business scenario

Say Amazon is using pega application for the sales department. The sales
department has different line managers for different sales category. For
example, Sales manager for electronics department, sales manager for
household department etc. As a Sales manager, daily they need to generate a
report on the total sales. The report should list all the sales cases that contain
the sales details like product name, amount etc.

Let’s assume, that sales manager uses the Pega manager portal.

Solution 1: The Sales manager is provided with a sales report in the default
Report tab. So, with this report, Sales manager can view the sales case any
point of time in the day. He/she can also alter the filter criteria to look at the
report for any data range. This is the power of pega in reporting. The reports
in the report browser are provided with an interactive UI that can be easily
handled by the business users for custom reports.

Automation is everywhere now. The above solution is a manual process, in

which Sales manager has to perform the report generation daily for the daily
report. Why can’t we automate the report and send the result to the sales
manager?!

Here comes the solution 2.

Solution 2: Any report in Pega can be scheduled to any users. So, the above
the sales report, created in the reports tab can be scheduled to run daily by
11.59 AM and the report PDF can be send to the sales manager.

Pega can do this very easily with little configurations 😊

 P a g e | 34

Let’s start with scheduling the reports 😊

What are the pre-requisites for report scheduling?

1. A working email account – make sure you have a working email account.

I have already configured an email account by following my own post 😊 You

can also do the same.

How to configure an email account & send outbound email from Pega?

I just updated the default email account with a valid email address.

Make sure the email account works by clicking test connectivity.

2. Agent ScheduledTaskProcessor is enabled – Make sure the agent that

comes under Pega-RulesEngine is enabled and running.

Always check the agent schedule instance, since it is a data instance and can
be different (updated manually) from the agent rule instance.

Note: If node classification is enabled, then check the agent schedule created
for backgroundProcessing node.

These are the two main pre-requisites for scheduling reports.

Let’s see the other steps one by one.

How to enable scheduling in a report?

1. Create a new Sales report.

As I mentioned before, reports can be easily created by the business people.

Now we will see how to create report from manager portal.

Again, I have an extensive post on creating reports.

 P a g e | 35

Configure reports in User portal

Step 1: Launch the case manager portal

Step 2: Move to the reports tab on the left navigation panel.

Note: Look and feel of the reports may vary based on your UI Kit version.

Step 3: Click on New report and select the right case type in the pop-up.

Remembering the requirement, I need to list all the sales that happened in
one day.

The solution is to run the report at 11.59 to list all the cases that were created
today.

Step 4: Include the filter criteria – Create date/time is equal to today.

Drag and drop the create date time field.

After that, click done editing.

Step 5: Enter a meaningful report name and for now place it under your
private category.

Step 6: Finally, you see your report under reports tab.

2. Enable scheduling on the sales report.

Step 1: Click on the configure icon and and select schedule.

Step 2: Click on the schedule option, it pops up a window.

Make a note on the header – it opens the perform harness of an instance.

 P a g e | 36

There are three main blocks

a) Task definition
b) Task scheduling
c) Task output processing

Task definition

Task name & Task description – Both are prefilled by default. If you need you
can always change the values.

Task scheduling

You can specify the Time at which the report to be scheduled. We have a
limitation here that it runs at round-off hours like 1 AM, 2 AM etc.

In our requirement, we planned to schedule by 11.59 PM, but now with this
limitation we need to run it on 12 AM and update the create date filter to
yesterday. So that at 12 AM, the start of the new day, it generates the report
for the previous day.

Task can be scheduled in two ways.

 One-Time only. Here you can specify the exact date on which it should
run.
 Recurring task. For this you get some additional fields to fill in.

Frequency – Specify whether it is for daily, weekly, monthly or yearly.

So, for every frequency, you get different options to choose.

For example – for daily, you can specify either to run on weekdays or on all
days; Please switch and check the possible options.

Start date – you can specify a date from which the scheduling should occur
 P a g e | 37

For end date, you can 3 options

1. No end date – keeps on scheduling without an end

2. End after (1 or more ) occurrences
3. End after a specified date.

In our scenario – I am going to run it by 12 Am, recurring and no end date.

Note: for testing, please update to the next hour to see the email, which we
will obviously do at the end.😉

One error, retry – On selecting this option, you can do some error handling if
the report fails.

Task output processing –

There you have 5 main fields to configure

Output file format – You can specify either PDF or Excel report.

Enable authorized users to subscribe to task notifications – Primarily the

operator, who created the scheduling who be default selected to be notified.
You see this in the next field. If other users should also need to subscribe the
report, then you can enable this option

Send notification to the following users – As I mentioned before, you can see
my name is auto subscribed. You can also add other users for subscription.
They will be auto subscribed.

The email ID configured in the operator rule form will used as the To address
for report. So make sure the email address is properly updated in the operator
ID.
 P a g e | 38

Attachment – We can either attach the report file with the email or send a link
for them to download.

Configure notification message – Click on the button and you can configure
the email message.

Click on submit.

You have successfully scheduled the report.

Step 3: verifies that you are auto subscribed.

Now the real fun part 😊 Let’s see the Pega architecture for the report
scheduling.

First thing that comes to your mind is – scheduling part should be handled by
agents in Pega, right?! We will see it.

1. Pega creates a new case instance of class Pega-ScheduledTask-

Reporting

Step 1: Go to app explorer and search for the class – Pega-ScheduledTask.

Step 2: You will see there are three child classes for the scheduled task.

Click on the reporting class to see its instances.

Step 3: You see the instance we created just now! Click and open the
instance to verify the details.

You can click update button to update the scheduling details.

We will see the update part while testing.

 P a g e | 39

Step 4: If you are interested more, then you can look at the flow and case
type corresponding to the scheduledtask case.

Note: most of the rules are in available mode and hence can be customized.
But make sure you customize only the extension points so that you don’t
make the new features in the later releases 😉.

If you delete the report, then corresponding scheduled task instance will be
cleared. Please test this on your own.

2. Pega creates a new queue instance for the agent –

ScheduledTaskProcessor

Go to App explorer and check the class System-Queue-ScheduledTask. You

will see a new instance created for our scheduled job.

You can also, click and open the instance to check the
minimumdatetimeforprocessing value.

You will see it is 11 PM GMT which is 12 AM my time.

3. You can see the agent rule under Pega-RulesEngine.

This comes out of the box.

Note: As a pre-requisite we already verified that the agent is enabled in the

agent schedule instance as well.

It’s time to test the report scheduling.

How to test report scheduling?

 P a g e | 40

Step 1: Update the scheduled task instance to the next one hour.

As soon as you update the time, the scheduled queue instance gets updated
with the right process time.

Tip: The OOTB activity pzPostProcess in Pega-ScheduledTask class is

responsible to delete the old queue instance and recreate a new queue
instance.

Step 2: You can click and open the instances of System-Queue-

ScheduledTask instances.

You will see the process on date to be Dec11 9 PM.

Step 3: Let the agent pick and process the queue item. You will see once the
agent picks up and process it successfully, attempts made will be 1 and the
process on data will be the next day 9 PM.

Step 4: Check on the Inbox.

Now this report scheduling is successfully tested. Now the next step, how to
promote the report scheduling to higher environments?

Usually the reports will be created in the lower environment and promoted to
the higher environments. Simlarly two more instances has to be manually
promoted to the higher environment for supporting report schedule

a) The Scheduled task case instance – PX-ST-3

 P a g e | 41

Note: To promote any instance manually, you need to include the pzInsKey in
the product rule.

Now you may get a question, if more than one people subscribed to this
report, will it be same in all environments. The answer is yes. All those details
stay within the case data.

Open the case PX-ST-3 and check the clipboard.

You will the pySubscribers list the operator ID.

Important note: Make sure before promoting the instance to higher

environment the subscribers are properly determined.

b) Promote the scheduled task queue instance – You need to do this.

Because you need a starting point to start the agent processing right. Once
the agent picks up for the first time, then it will requeue based on condition
and manage on its own.

We are at the end of this post. Let’s see a summary of report scheduling

1. Any report in pega can be scheduled to any pega user.

2. You need to enable the agent and have a working email account as a
pre-requisite
3. Pega creates a scheduled task case instance for every report
scheduling.
4. Pega maintains a standard queue scheduled queue instance that will be
attended by a OOTB agent to process and send out the email.
5. Email address configured in the operator form will be used as To
address.
6. You need to promote both the scheduled task case and queue instance
to higher environments.

Hope you enjoyed this post on report scheduling. Look out for a business use
case in your project and try to implement the same 😊. See you all in my next
post. Take care.
 P a g e | 42

Agent and Agent Schedule in Pega

Published May 13, 2017 by Premkumar G

87

Introduction

In this post we will see in details about Agent and Agent Schedule in Pega.

Most of the applications rely on processes that operate at the background

without human intervention.

Imagine there is a requirement to send a status report to the reporting

manager every day by 8 p.m.

You can code it like ‘providing a button and by clicking on that, we send an
email containing the status report’. But if you do like this people will laugh at
you.

Here comes the Internal background process to provide solution for this
requirement.

In Pega platform, ‘Agent’ rule serves as an Internal background process.

To know about requestor type involved in batch processing, please visit my

post below.

http://myknowpega.com/2017/05/13/requestor-types/

Agent and Agent schedule in pega, both belongs to background processing

What is an Agent rule?

 An agent is an internal background process operating in the server on a

periodic basis.
 Each agent rule can contain individual agent activities for different
processes.
 Agents come under SysAdmin category and each ruleset can contain
only one Agent rule.
 P a g e | 43

How to configure an Agent rule?

Agent rule don’t belong to any class.

In the Agent rule form, we have three main tabs.

1. Schedule
2. Security
3. Nodes

Schedule tab:

a) Scheduled agents

In the scheduled agents, you can add ‘n’ number of activities.

Agent Name – Provides the name of the agent (Appropriate description).

Pattern – Periodic/Recurring/Startup.

 Periodic scenario: Imagine you need to update a work item every one
hour. In the interval field, you specify the seconds as 3600.
 Recurring scenario: You need to send mail daily at 1 pm. Use Interval
field advanced option, to set the time daily to 1 pm.
 Startup: Only when the server starts ( not used often).

Mode – Standard / Advanced (We will have deep explanation below).

Category – Not a required field. Use it for recording purpose.

Enable – True/False. We can enable or disable the agent.

Class – Class of the Agent activity rule.

 P a g e | 44

Activity Name – Agent activity name.

Params – Activity parameters.

Max Records – Shows how many records the agent should process before
going to sleep. Usually applicable for standard agents.

Auto Queue Management – True/False.

What is Auto Queue Management (AQM)?

This is applicable only for standard agents.

Imagine a scenario where you need to update a work item in the background
based on SLA.

The agent activity tries to acquire the lock for the work item, but is already
locked by other agent. Now basically the agent activity cannot update the
work item (fails). In this scenario, if

 AQM is checked, then the agent re-queue the item for later processing.
 If not checked, then the agent gets only one chance to process it and do
not persist the queue item.

Agent wide settings

Enable this agent – True / False. Enable the Overall agent rule.

Interval – Default interval seconds. Used when if we don’t provide the Interval
for Individual agent activity configurations.

Note: these configurations can be updated in agent & agent schedule

Security tab:

Access Group – Applicable only for Advanced agents. Used to identify the
agent activity rule.
 P a g e | 45

Access group -> Application -> Builds ruleset list -> Agent activity rule.

Bypass Authentication – True / False – Agent activities may be configured to

use authentication (Activity security tab). You can bypass those authentication
by selecting true.

Nodes Tab:

We know Pega system can run on different nodes using different servers.

This tab lists the nodes, where the agent schedules are created. We will
discuss about Agent schedule later in this post.

How a standard agent works?

Requirement: Route the Leave request case to manager queue for approval.

 If the manager didn’t approve the next day, the send an Email to him.
 Even after 3 days if he didn’t approve, then Auto-approve the request.

This requirement can be achieved using SLA on the assignment shape of

manager queue.

As part of development, we just configure an SLA and don’t mind how the
background SLA works.

I am going to take you to a trip and explain in detail how the background SLA
process works.

SLA process:

To know the basic of SLA, please visit my exclusive post on Service level
agreement.

http://myknowpega.com/2017/05/17/service-level-agreement/

Front end:
 P a g e | 46

 When the Leave request case reaches the assignment shape Assign-
.AddAssign gets called.

 This activity queues an entry with Event as “goal” to agent “Pega-

ProCom:ServiceLevelEvents”.
 Expand 2nd & 3rd step to get the details.
 Now the Goal event (1 day) is queued to standard agent.

Back end:

 Agent – Pega-ProCom

 System-Queue-ServiceLevel.EstablishContext is responsible for Open

& lock the assignment and Switching the access group. (AQM
functionality)
 Process Event – SLA agent activity.

a) When the manager didn’t approve the next day

The agent activity runs and starts processing the queued Goal event. Use
activity ExecuteSLA to set the Urgencies and execute the escalation activities.
It Re-queues the entry again for Deadline event.

b) When the Manager didn’t approve for the third day

The agent activity runs and starts processing the queued Deadline event. Use
ExecuteSLA to set the Urgencies and execute the escalation activities. Here
no passed deadline, so no more queue entries are added again. Leave is
auto approved after deadline.

Go through the activities ProcessEvent & EstablishContext in System-Queue-

ServiceLevel class.

How an Advanced agent works?

 P a g e | 47

Advanced agent do not automatically use the Auto Queue Management

(AQM).

All the transaction items need to be carried out in agent activity. We can
configure the activity to re-queue if some error occurs.

Key differences between Standard agent and advanced agent:

1. Standard agent uses the access group of the user who queues the
entry, while the advanced agent uses the access group specified in
Agent rule or requestor type.
2. Standard agent supports AQM, while advanced agent do not.
3. Standard agent wake and run only when there are queue entries with
available lock, while the advanced agent runs even if there are no
queue entries. This is because advance agent is responsible for agent
queue processing.

Issues you may face in advanced Agent:

Imagine the same scenario discussed above. You need to configure an agent
to update a work item. Now you configured the agent as Advanced agent and
made it available in 3 nodes. Here, Object contention occurs, since advanced
agent activity should handle the locks. If the same is configured using
Standard agent, then there won’t be any locking issue.

“Prefer using standard agent over advanced agent”.

What is Agent Schedule?

 Here you can see the relation between agent and agent schedule in
pega.
 As we discussed before Agents can run in multi nodes.
 Imagine a scenario where you need to update agent run Interval from
300 seconds to 30 seconds in particular node. To solve this Agent
schedule comes in Handy.

 Agent schedule is a data instance and can be updated in any

environment.
 Here Pattern, Interval, Enabled, Access group etc., are editable and can
be updated for a particular node.
 P a g e | 48

 You can check the node ID in the ID header field.

 The changes reflect immediately once updated and saved.

How to create Agent schedule?

There is no need to create the agent schedule manually. There is an OOTB

Master agent which monitors the Agent rules. If there is any new agent rules
or if there is any update the Master agent generates, then the appropriate
agent is scheduled. This is the relation between agent and agent schedule in
Pega 😊

How to debug an agent?

Use SMA.

 In the Agent management, you can check if the agent is running or not.
If there is some error and the agent has stopped, then you can see the
stack trace or log files.

 Tracing the Requestor.

We may be aware of a mantra,

Stop -> start -> Delay -> go the requestor management and trace.

Have you ever wondered, why you do this?

Explanation:

 As per my previous post, I mentioned Agents use batch requestor type.

 Requestors will be assigned to agent activities, only when it runs. When
agent runs, it requests a batch requestor.
 So when you stop and start the agent, a new batch requestor (B) is
assigned. You will delay and trace that requestor from requestor
management page.

Hope you get the basics about agent and agent schedule in Pega
P a g e | 49