Compliance Score, Guardrail Warnings and Custom Warning

In this article, we will talk about the application quality metrics – Guardrail warnings and compliance score. We will also see how we can add/suppress guardrail warnings for different rule types.

This tutorial is demonstrated using Pega 8.5.1 personal edition.

Application Quality

Think an insurance providing organization wanted to use Pega software to build a sales application for their sales department employees. They wanted to go live and use the application in the coming quarter. They hired a matured Pega team and started building the application at rapid speed. With quicker delivery in mind, certain best practice adherences were violated. They were able to go live with the deadline of 3 months. Business is very happy so as the Pega team!

Happiness Index is sky high :)!!

What you think would have happened in the following weeks??

– Lot more bugs started to appear in the Production

– The application is not built with reuse in mind, and so with the upcoming new features, the application needs to be rebuilt a lot to accommodate the new features.

There is no built for change!!

To counter the bugs and also to deliver the new features, the organization hired a second Pega team.

– The new team started to complain about the code quality and maintenance (difficult to understand on their own). A lot of effort is spent on knowledge transfers.

The Happiness Index went rock bottom :(!!

They planned a retrospective and found one thing that could have made a huge difference!!

Investment in the application quality.

(The above story can be anyone’s amateur project experience 😉)

Normally the quality of an application can be defined using different characteristics and can be broadly divided into two categories.

a. Functional quality

How an application complies with the given design, based on the functional requirements.  In the development environment, we can create unit test cases for the rules we develop and execute it periodically or during the code deployments to verify if the application complies with the functional requirements.

b. Structural quality

How an application complies with non-functional requirements like robustness or maintainability of the application. Pega engine has 200+ ( I may be wrong at the exact count!) guardrail warning checks for the rules we develop and generates a compliance score for the application.

With the Pega 8 version, a new dashboard is introduced to monitor the application quality.

Open the Pega designer studio and navigate to

Configure -> Application -> Quality -> Dashboard

There you see the application quality for the application.

This is just my sample application and so the number of rules is very less and hence the rule warnings impacted the guardrail/compliance score of my application. The weighted score is only 47!!

I haven’t created any unit test cases, so it is 0%.

In this tutorial, we will concentrate only on the Guardrails part.

Let’s zoom into the first block.

Click on view details. That should display the Application guardrails landing page

Tip: Alternatively you can also reach this landing page by following the below navigation path. Configure -> Application -> Quality -> Guardrails

There are 4 tabs.

Compliance score tab

 This gives an overall picture of the compliance score of the application.

It also gives details about how many application security checklist tasks are completed. Security checklist is out of scope for this tutorial. You can follow the link to find more details on security checklist tasks

https://docs.pega.com/security/85/security-checklist

Weighted score = Compliance score = 47

% complaint rules – 82%

Important note: Do not confuse the Weighted score with the % complaint rules.

% complaint rules – (( Total number of rules – Rules with warnings)/Total number of rules) * 100

                               = ((38-7)/38) * 100 = 81.57 = % of rules are complaint (without warnings).

A little later,  we will see the Pega formula that calculates the compliance score for the application.

Benchmark for compliance score

– Pega recommends having a compliance score of 96% for each of the pega applications.

– In a practical scenario, for the legacy applications, this may be difficult to achieve. In such cases, you can define your own benchmark for your application compliance score, say 90% and try to stay above the benchmark with the new code changes.

Tip: Pega deployment manager provides a pipeline task, to verify the guardrail score of the application and stop the deployment if it falls below the benchmark score

In this tab, you will also find the details about the system performance metrics.

You can use the PDC link to check more on the alerts.

Compliance details tab

This tab gives 3 main details

Warning Impact  – You see 1 in red and 2 in amber.

It is just on one calculation on warning type. 1 severe warning and 2 moderate warning.

Severe warning needs to be fixed as soon as possible and moderate warning needs to be fixed before going production.

Warning age – self-explanatory.

Application risk introduced by the operator – Based on the developers who contribute the rules to the application, it shows the share per developer. Since In my personal edition, I am the only developer for the application, I contributed 100% application risk 🙂

Warning Summary tab

This tab gives details about the warnings, per rule type, severity and other filters.

In the top block, you see the filters that can be applied to get the warning summary.

Application/classes – In real-time when you have multiple built-on applications, you may need to select the right applications for which you need to get the warning summary and fix it. You can use the application link, to select the right applications in the picklist. Similarly, you can also filter on classes.

Dates – You can also filter on modified from date and to date.

Severity

Warnings are classified into three types

1. Severe – This is of higher guardrail rank/risk and needs attention right away. The impact can be huge and so it should be solved as soon as possible.

2. Moderate – This is a medium-level warning and should be fixed before going live to production.

Severe and Moderate warnings impact the compliance score of the application.

3. Informational – This is more like an informational warning or nice to have to be fixed. This type of warning will not impact the compliance score of the application.

Tip: When you want to fix application warnings, you can start with severe priority and then move down the severity level.

Justification – Pega also provides us with an option to justify the warnings. In an exception situation where you cannot fix the warning, you can justify it with your message. This will be recorded and can be informative in the future for anyone who looks at the warning.

Justifying a rule improves the compliance score of the application!, but don’t just try to justify all warnings 😉 First try to fix it!!

Okay, now let’s filter only the unjustified severe warning.

I see only one severe warning – use data transform for the activity rule – product details.

Click and open the rule.

You see the red warning banner on the top. You can click to view the warning details, where you get an option to justify the warning.

I created the above rule for one of my previous post demo, which is why it looks bad coding. I could have replaced the activity and used the property-set using the data transform.

To fix this,  I will create a new data transform rule withdraw the activity rule in a higher version (if it already migrated to production) and change the references to use the new data transform rule. In this way I will be fixing the severe warning.

Note: Pega recommends to use data transform in place of activities, because of the java complexity of activity rule type that may impact the performance at run time. Data transform can be quite faster than the activity rule.

As soon as I withdrew and save the rule, the warning disappeared. This is because guardrail warnings are not applicable to the withdrawn rules.

Check the compliance score now after fixing the severe warning.

You see it is increased from 47 to 73. That is a big leap (also because of my small rulebase)!!!

Now let’s check how pega calculates the Compliance score.

You see severe unjustified warnings have a higher weightage of 10. Severe justified has a weightage of 2 which is lower than unjustified moderate warning.

So start fixing your unjustified severe warnings, If it cannot be fixed, code for a reason then don’t forget to justify.

Warning details tab

This just gives a list report with more details on each warning.

You see you can filter the report based on application or classes.

In all 4 tabs, in the top right, you may find an option to export the report to Excel and also schedule the report periodically via email.

So we are now clear on how the compliance score is calculated and different reports and metrics on different tabs.

Why adhering to guardrails is so important in a pega application?

Now an interesting question.

How Pega implement the warning checks for each rule??

Let’s figure it out ourselves.

Step 1: Create a simple activity on the available state as shown below.

Step 2: Before saving the rule, start the tracer and save the rule.

You see the StandardValidate rule from Rule- class invokes the CheckForWarnings activity.

Step 3: From the activity explorer, filter for the activity name – CheckForWarnings

You see the same activity exists for different applies to class, it means different rule types.

Open the CheckForWarnings activity in Rule-Obj-Activity class.

You will find different checks for the activity rule type 🙂

There in Java step 15, you see it adds a message pxUseDataTransform using function pxADdGuardrailMessage from pega WB ruleset.

Step 4: the function pxAddGuardrailMessage adds the message.

Step 5: In the activity rule form – Actions – View XML, you will find the pxWarnings pagelist

You may get a question like, we never passed the warning severity type or warning type? Then how does the values are populated?!

Did you note  the pxWarningMessage property holds the message name – pxUseDataTransform

Open the message rule form.

You got the answer 🙂 We define the severity in the message rule form.

Note: Only when you select the message category as Warning, then the Severity and application impact dropdowns displayed.

The same message is displayed in the affected rule form.

These warning details (.pxWarnings) get persisted with the rule form and re-valuated every time on save.

Pega uses the class Index-Warning that is mapped to pr_index_warnings table to Index the warnings per rule and save into the DB table with reference to the rule key.

The reports which you see in the warnings summary landing page, use the pr_index_warnings table to query and display the result.

Now it is all clear, how pega implements the check for warnings per rule type.

On rule save -> StandardValidate activity -> CheckForWarnings specialized under ruletype class -> The function pxAddGuardrailMessage  uses the message rule and adds the message to pxWarnings/pxWarningsToDisplay page list property.

Now some hands-on experience!

Requirement – In the same Insurance organization, new team started complaining that it is very difficult to understand the rule usage. LSA asked all the developers to enter the usage field in all ruleforms history tab.

LSA wants the teams to start with the activity rule and display the warning message if it is missed in the activity rule form.

How to write custom guardrail warnings?

You find the standardvalidate activity calls the extension activity CheckForCustomWarnings

Step 1: Save as the extension activity or create a new activity of the same name in applies to class of Rule-Obj-Activity.

Step 2: Create a new message rule

UsageIsEmpty.

Define the severity as Informational

Important note: For your custom warning, be careful in defining the severity for the warnings. Always keep in mind if you make severity level as moderate or severe, it will impact your compliance score

Step 3: Use the pre-condition condition in the custom activity and add the message using the function.

Use Live UI to find the property name for the Usage Field. It is pyUsage.

Add a pre-condition to check if pyUsage is null, if yes, execute the Call – function – pxAddGuardrailMessageWrapper

The function doesn’t return any value

Step 4: Now test an activity by removing the usage field, you should see the informational warning message.

Yessss 😀

We have successfully added a custom warning message for the activity rule type.

You see there are two informational messages – Pega Unit Warning and UsageIsEmpty.

Is there a way to suppress the default guardrail warning?

It is highly not recommended to remove the out-of-the-box warnings, but in unusual circumstances, you can do so.

Technically, In the extension activity, we need to remove the right pega unit warning page from the two pagelists – pxWarnings and pxWarningToDisplay

There may be a Java step solution in the web, to remove the page from pagelist. But having a java step is against guardrail. I would recommend not to use the java step, instead follow the below steps!

Step 1: Save as the extension activity or create a new activity of the same name in applies to class of Rule-Obj-Activity

We will use RemoveDeletedObjects function to remove the specific page from a pagelist.

Step 2: Loop the pxWarnings and pxWarningsToDisplay pagelists and set the pyDeletedObject property to true based on the pre-condition

Step 3: Add a property-set to invoke the function to remove the deleted objects. (You can also use Call function method)

A short peek at the function – RemoveDeletedObjects

Tips to avoid/fix the guardrail warnings on time

1. Developers should always keep an eye on the warnings banner and should fix the warnings at the time of development.

2. In the branch merging wizard, Pega provides the application quality dashboard. Reviews can verify the code quality and approve the merge only after fixing the guardrail warnings.

3. Make sure to not introduce new warnings that will impact the compliance score of the application. If you use the Pega deployment manager for deployments, use the guardrail compliance score check task over the benchmark score. If the score goes below the threshold, then the pipeline will fail and deployment will not continue.

4. You can use the scheduling functionality to periodically send an automated email to interested stakeholders about the application quality and warning summary.

We are at the end of the long tutorial!!

As a summary,

– Pega provides an Application quality dashboard that helps to monitor different characteristics of the application – Guardrail warnings, security checklist, unit test case coverage.

The compliance score of an application gives an overview of application quality and the recommended score is above 96.

– Warnings severity is classified into three groups – severe, moderate and informational.

– Severe and moderate warnings impact the compliance score and need to be fixed or justified.

– Warnings per rule are saved under Index-Warning class under pr_index_warnings table.

– Pega provides extension activity to write custom warnings per rule time.

– pxAddGuardrailWarning function uses the message rule of category warning to add the warning message to the rule form. The severity level can be configured in the message rule form.

– Though it is not recommended, you can also suppress the OOTB warning messages.