Creating custom rules in PRPC

You can find the first part of this post from here

What do you think one of the frequently asked question in PDN forum, any guesses?, it's about Excel integration with PRPC, but ironically by the time of this writing PRPC still does not support a rule based approach to the problem of Excel integration. So are we in a dead-end, frankly not. Due to the elegant design of PRPC, we can create our own custom rule to accomplish the task. 

Welcome to the second post of the series "Creating custom rules in PRPC", as I pointed out in the first post, in this post I am planning to systematically lay down the steps that need to be taken in order to create a custom rule.

Word of caution: Most of the things I am writing here are, what I called observable knowledge, meaning - understanding how something works literally by observing the system and in case of PRPC reading the rules in the system without going through a formal How-To documentation, reason being we do not have such documentation, this is the only article I was able to find in PDN regarding custom rule creation. According to the PDN there had been some documents, but not anymore. Search for the lost pearls didn't go well either:). So if you feel that I have missed something please feel free to correct it by leaving a comment.

Let's start with a question - Why do we need to create a custom rule ? - To impresses our colleagues, while that could be a possible reason, we will be able to find a better answer if we look at the definition of the custom rule again. 

Custom rule is a rule which describes a process / execution pattern which does not available as out of the box rule in PRPC

One of the the key phrases with in the definition is "which does not available as out of the box rule in PRPC". So we should never create a custom rule if we can find something alternative with in PRPC as an OOTB feature.

Following list explains what needs to be done to plan and finally implement a custom rule

  • Plan and Design
  • Create rule class and properties
  • Create a rule form
  • Create a model rule in the rule class
  • Create a validation activity
  • Create a custom warning activity
  • Create the activity which does the actual rule logic
  • Map the custom rule to a new table cloning pr4_rule table

I will explain each step by giving reference to the Connect-Excel rule, please try to relate these steps to a common rule you are familiar with and try to see how Pega has done the same steps with reference to the rule you are examining.

Plan and Design

One of the most important step that has to be done before doing anything is to plan and design the custom rule. Always wear the end users hat and look at the custom rule from their angle as well. Consider the most critical functionalities that the end user is expecting from your custom rule and think about the end user profile (Technical / Business) while doing the design.
Plan and Design step can be sub divided in to four steps.

Finalize the initial scope of the rule in terms of functionalities that the rule offer

In Connect-Excel rule there are four main functionalities

  • Reading data from a table structure
  • Reading data from a cell
  • Writing data to a table structure
  • Writing data to a cell

Sketch the UI of the rule to better align with the functionalities of the rule and to align with the end user knowledge of the domain.

In Connect-Excel rule there are 2 main tabs to distinguish reading and writing functions of the rule, inside those two tabs fields are aligned such a way that users will be able to better relate to the domain that they are working with, which is an Excel sheet with the rule.
This UI mock-up will be very helpful in the 2nd step when you are creating the properties

Setup/configure the PRPC environment to include any third party libraries or jar files

Depending on the problem, you might use external jar files or libraries that will deliver the functionalities of your custom rule, please put them to the correct class paths so that PRPC will identify those in compile time and run time.
Apache POI package was use to implement the Connect-Excel rule.

Workout the algorithms that will describe the behavior of the custom rule

It is always better to workout the algorithms offline before creating the full fledged rule, in terms of the Connect-Excel rule, basic operation of reading and writing was carried out with the Apache POI methods.

Create rule class and properties

As you all know classes play pivotal role in PRPC Object Relational Model, where you as the developer is abstracted from low level CRUD operations, so if you need to work with instances of a rule, first you need to have a class to start with. Not any other class, but a class which inherit from Rule- class, why, as I explained in the first post, when you inherit from Rule- class or any one of its descendants you get the Ruleness to your rule. The four magical spells.

So in Connect-Excel rule I have created a class called Rule-Connect-POI-Excel, as you can see it inherits through the the Rule-Connect- class, since Connect-Excel rule is related to connecting to a external source inheriting through the Rule-Connect- was the obvious choice.

PRPC class rule for the Connect-Excel custom rule

Normally when a class is created inheriting from Rule- class PRPC maps the class to pr4_rule table in the PegaRULES database, we will see at the last step of this process how we map our new rule to a new table. 

With the class created now it is the time to create the data model of the rule, the UI mock up will be very useful in this step as you have to map the UI with properties.

The best way to understand the property mappings in Connect-Excel rule is to go through the following screenshots.

PRPC Property structure for the Connect-Excel custom rule

PRPC Property structure for the Connect-Excel custom rule

Connect-Excel custom rule with property structure

Create a Rule Form

Up to now we have created the class and the properties of the new rule, in this step we will be creating the actual UI of the rule, which we call Rule Form in PRPC.

There are two ways in which we can create Rule Forms

1. The classical Rule-File-Form approach using Form Builder Tool

2. The new Rule-HTML-Harness approach starting from version 5.5

The Rule-File-Form approach is still widely used even in 6.2 version of the PRPC application, this is one of the biggest reasons why PRPC developer environment is IE only, reason being Rule-File-From use XML Data Islands, which is IE only, but from version 5.5 Pega has started to use Harness rules to define the rule forms, which is the best way to go forward.

I have used the Rule-File-Form approach to define the UI of the Connect-Excel rule

If you open an existing Rule-File-Form rule (e.g Connect SOAP) initially you will be overwhelmed by the amount of source code it has. but as always Pega has given a nice abstraction to us, called Form Builder, using Form Builder it is very easy to create a Form rule with in minutes.

The best way to understand the Form Builder is to investigate Form Builder layout of a know rule like Connect SOAP. Open existing Rule-File-Form rules and try to see how Pega has created the form rule layouts.

Rule-File-Form of the Connect-Excel custom rule

Form Builder layout of the Connect-Excel custom rule

As you can see while you configure the tree structure according to your rule form UI by mapping properties of the rule class with UI elements,  the Form Builder is creating the complex underline Form Rule UI source code. 

If you can remember, in the Connect-Excel rule form, you can see a color picker component within the rule form itself, which you have not seen in Pega supplied rule forms. This demonstrate the power of PRPC to express anything you want in any level of the product, since PRPC is a web application, even while we use highly abstracted tool like Form Builder we can use normal web technologies like HTML, JavaScript to accomplish custom functionalities.

So finally after building the Rule Form you have to attach it to the rule class so that PRPC knows which UI to display when you want to do CRUD operations on an instances of the new Rule class.

Mapping Connect-Excel new rule from in the class advanced tab

Updated PRPC menu with new Connect-Excel rule

Create a Model rule in the rule class

Model rule is used to initialize the rule properties of the new rule.

Model Rule which initialize the properties

Create a Validate activity

Create an activity rule with the name Validate in the rule class and put all the custom validations of the new rule. PRPC will pick the validate activity using rule resolution and execute while the rule is being saved, resulting errors if errors are found.

Validate Activity of the Connect-Excel custom rule

Custom Errors

Create a custom warning activity

If you are planning to add custom warning to your new rule, override the @baseclass CheckForCustomWarnings activity and save it to your rule class,

Create the activity which does the actual rule logic

Now we have come to the main step of the new rule creation process where we create the actual activity rule which carry out the logic behind the new rule.

Before describing the steps of our activity, let’s try to understand how we would normally use a connect rule which is available in PRPC. (e.g. Connect-SOAP).

So when we want to call a web service we will use the Connect-SOAP activity method and pass the parameters which the method is expecting. One of the parameter is name of the Connect SOAP rule. With that information PRPC magically does something and we have our data we requested.

So what does PRPC do, it basically does two things,

  • Opens the passed rule instances to the clipboard with the help of rule resolution
  • Apply the logic (in this case call an activity which has the logic) using the data which is in the rule 

You will be able to see this if you examine the generated java code of an activity with the Connect-SOAP method.

We will be doing the same thing, but with small changes because of some limiting factors in PRPC.

So let’s start,

Sadly as soon as we start we are hitting a wall, we all would like to have a catchy name like Connect-Excel to call our new rule right, but in PRPC you can not create Rule-Methods rules, this is what you have in help under Rule-Methods in bold letters.

You cannot update methods, create new methods or override standard methods

So we have to find another alternative way to call our new rule, this is what I did, I created an activity with the name Connect-Excel and put the above described two steps in to that activity and use it to call our new rule. So when the developers want to use a Connect Excel rule they would call the Connect-Excel activity with proper parameters and you have the results. That was the best we can do with the PRPC limitations.

Parameter tab of the Connect-Excel custom rule execution activity

Having said that, Actually Pega has given a way to execute new rule type with an instruction called “Rule instruction”. The only reason I went with the first approach is to get a more catchy name.

So we have seen the activity signature and how you would go and call the activity to get the work done. If you are a developer who is using this new rule those information would be enough.

But we are implementing a new rule here, so let’s see how we would write the implementation code, the real stuff that will do the work.

Execution logic of the Connect-Excel custom rule

As you can see in the first step Connect-Excel rule is being opened with the keys that was passed to the activity as parameters and in the second step the actual logic is written using the POI package.

Clipboard structure of a Connect-Excel custom rule

I will be writing the remaining part in the next post, till then happy reading.


  1. Have you written the remaining part?

    1. Hi Indrajith,
      Thank u for sharing this unique article. Definitely a life saver.

      Have a requirement in a RPA automation, the robot opens a remote excel file laying in the network to pick some values. Another team from the same company should be able to update the excel while robot is processing . The thing what I noticed is, if any user uses the same excel opened by the robot, there will be no exceptions.
      But, if somebody tries to open the excel again in their machine while the robot is in process, the bot will throw an exception. So, my approach is to keep two copies of the excel called "working copy (one that the RPA opens)" and "remote copy" and then wait until the robot finishes the process and save as the remote copy to the folder where the working copy is the robot shows a model dialog asking whether to replace the existing file. which the RPA bot can’t handle. How should I handle this requirement?
      We shouldn't be restarting the bot after modifying the excel. That’s the requirement.
      Is it possible to import the excel to a data table so that the excel data is in the memory and copy the data in to the memory every time the process starts? But still there will be an error if the user tries to update the excel while automation tries to copy the excel data to the data table. So want to know if somebody has solved a requirement like this.

      But great job man, do keep posted with the new updates.
      Corbett Kevin

  2. hi indrajith,
    this is vishal
    i was an filenet developer now i was shifting to pega prpc with my company permision.
    can u help me with my doubts on pega prpc.
    how can i be in touch with with you.
    thanking youvishal

  3. Hi Vishal

    Please visit Pega Professionals Community on Google+


  4. Indrajith, a very interesting post. I am reearching more on the custom rule development and was wondering if you can help with what Rule Instruction means and where can it be defined? Thanks for your help.


Post a Comment

Popular posts from this blog

CSSA PDN Links Compilation