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 ruleIt 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.
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.
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.
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.
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.
Create a Model rule in the rule class
Model rule is used to initialize the rule properties of the new rule.
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.
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.
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.
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.
I will be writing the remaining part in the next post, till then happy reading.