Activity methods & its usage – Part 1

Most of us irrespective of years of experience would be aware of activity rules in PEGA. We would have at least configured one activity with a complex method [Property-Set] 😛

• An activity is an instance of class Rule-Obj-Activity.
• An activity can be used to automate processing.
• PRPC converts the instructions in the activity into server-side Java code. At run-time, this Java code gets executed to perform the intended tasks.

An activity rule can consist of <<n>> number of steps each of which refers to a method. So, it’s required to understand the usage of methods provided OOTB in order to write an efficient activity.

Let’s explore these methods in detail with a real-time example. The methods are explained in the order of activity rule’s auto-complete values.

Business Scenario

Let us consider a passport application built for OSP organization. End to End process of this application involves Filling Application Form, Evaluating Eligibility Criteria, Verifying Documents and Dispatching Passports.

CALL

• PEGA recommends limiting the number of steps in an activity to fewer than 25 steps. It is suggested to split logic into multiple activities rather than coding everything in an activity. Grouping logic into smaller units ensures re-usability and maintainability.
  
• An activity can be invoked from other activity using the Call method.

Scenario

When an applicant submits the application form, it should be validated and the data should be submitted to an external system.

Implementation

• This logic can now be grouped into two smaller units,
  • Activity 1 -> to validate collected information
  • Activity 2 -> to submit validated data to an external system.
• Activity 2 [submitting data to the external system] can be called from Activity 1 [Validating form] using the Call method.

Method Params

• Call method when expanded shows the list of parameters defined in the called activity along with a checkbox “Pass current parameter page“.

• Parameters to the called activity can be passed as name-value pairs or by passing the current activity’s parameter page.
• Selecting the checkbox “Pass current parameter page” ensures that the current activity’s parameter page is getting passed to the called activity which can be referred or updated in the called activity if required.

Debugging

We can debug the execution of the Call method using the tracer tool. Both calling activity and called activity events, parameter page & local variables can be examined in the tracer tool.

Pointers To Remember

• Call method can only pass parameters to the called activity but not local variables.
• Call method executes the called activity and once completed, it resumes the processing of calling activity. It uses the same requestor and thread to execute both the activities.
• Pass current parameter page is mandatory when the called activity has an OUT parameter which is to be used in the calling activity.

BRANCH

• Branch method functions similarly to the Call method with an exception that, Call method returns the control back to calling activity and resumes the execution of calling activity, whereas the branch method will not return the control back to calling activity. No steps after the Branch are executed.
• When the system executes a Branch step, control transfers to another activity. Execution of the current activity is paused & the processing of the current activity ends when the branched activity execution is complete.

Scenario

When an applicant submits the application form, it should be validated and the next course of action is decided based on the validation result.

• If form validation fails -> Applicant should be notified and the form data should not be submitted to the external system.
• If form validation success-> Form data should be submitted to the external system.

Implementation

• This can be implemented by having a branch activity to send an email notification when validation fails. If not, logic to send data to the external system gets executed.

If (Validation fails)
{
The system executes Branch step to send email notification & ends the current activity execution
}
else
{
System skips sending email notification and executes logic to send data to the external system
}

Debugging

We can debug the execution of the Branch method using the tracer tool. Both calling activity and called activity events, parameter page & local variables can be examined in the tracer tool.

Pointers To Remember

• Branch method can only pass parameters to the called activity but not the local variables.
• Branch method executes the called activity synchronously using the same requestor and same thread.
• Branch should be used when the system does not want to execute steps after branch in the calling activity.
• Most of the OOTB APIs like createWorkPage, UpdateWorkObject, Validate makes use of branch method to skip activity execution in case of errors.

COLLECT

• Collect method is used to invoke collection rule during the execution of an activity.
• Collection is a rule instance of class RULE-DECLARE-COLLECTION.
• Collections enable us to define a set of rules that are executed in sequence under the specified conditions and contexts.
• Collection rule is available under the Decision category in records explorer.

Let’s now look into a real-time scenario to implement collection rule whereas a detailed explanation of collection rule & its back-end execution will be covered in our upcoming post.

Scenario

The passport verification process involves a different set of business logic to evaluate for Millennial [Age below 30] and Senior Citizens. Based on the outcome of the validation, Applicant & OSP Manager should be notified of the status of the application.

Implementation

• The applicant provides their Date of Birth and age should be calculated from DOB to decide the category of the applicant [Millennial/Senior Citizen]. This can be handled using pre-action available in the collection rule.

• To validate the information, we can have activity/data transform specific to each category [Millennial/Senior Citizen] which will be conditionally invoked based on the age of the applicant. The entire logic can be placed in a collection rule which will act as a single source of reference.

• As per the requirement, once the validation is performed email notification should be sent to the applicant on the status of the application. Emails with different subject/content should be sent for Millennial and Senior Citizens. This can be implemented by configuring the “SendSimpleEmail” activity as a response action of step/category.

• As per the requirement, the OSP Manager should be notified of the status of the application once all the validations are completed. This can be handled using post-action available in the collection rule.

Method Params

Collect method when expanded shows the list of parameters defined in the collection rule along with an option to “pass current parameter page“. Parameters of the collect method act similar to Call/Branch method.

Debugging

We can debug the Collect method using the tracer tool without enabling any additional settings in the tracer. Page context, Parameters & local variables used internally can be easily examined using tracer. A sample tracer event of application with category Millennial [Age<30] is shown below.

Pointers To Remember

• The need for collection should be wisely decided during our implementation. A few examples are: calculating discount rates in online shopping based on the customer profile, calculating premium in insurance based on jurisdiction, calculating loan interest based on the principal amount, etc.
• The collect method can only pass parameters to the Collection rule but not the local variables.
• Collect method executes the Collection rule synchronously which uses the same requestor and same thread.

JAVA

• Java is a method that is used to include custom java code in an activity.
• Java code in activities is referred to as inline Java. Basic java coding skill is a must to implement/debug these methods.
• A real-time scenario to use Java code is discussed below.

We use java in writing functions to promote re-usability which can be explored in our upcoming post.

Scenario

Assume that application/case information is received in JSON format from an external system . PEGA should parse the incoming JSON and map it to the clipboard for business processing.

Implementation

• Custom java code can be used to parse the incoming JSON object.

• Message is a local variable that contains the actual JSON.
• adoptJSONObject() is an Engine API in PEGA which can be used to parse the incoming JSON into a clipboard page.

Debugging

• We can’t debug Java code directly using the tracer, instead use log messages.
• Let’s now see how to debug the incoming JSON string in the above-mentioned java snippet. Custom code can be added to log the message whenever required. It can be verified in PEGA logs after its execution.

Pointers To Remember

• The usage of Java code should be minimal in activity. If required, it can be converted into functions and can be directly invoked from the activity using the “Call-Function” method.
• Local variables in activity can be directly used in java code without any explicit declaration in code [like Message variable in above snippet].
• Proper exception handling should be done during inline java usage.
• Below are few commonly used snippets which might be required when writing a basic java code for our application need
  1. Initializing a clipboard page from java code
     • ClipboardPage <<PageName>> =null;
  2. Accessing data from parameter page
     • String <<var>> = tools.getParameterPage().getString("<<Param Name>>");
  3. Setting value to a parameter page
     • tools.getParameterPage().putString("<<ParamName>>", "<<Param Value>>");
  4. Referring DSS value in java code
     • String <<var>> =tools.getSystemSettings().getDynamic(<<Ruleset>>, <<DSS Key>>)

QUEUE

• Queue method functions similar to Call method with an exception that, Call handles the execution synchronously in same requestor, whereas Queue handles the called activity execution asynchronously in a different requestor which promotes parallelism.
• A requestor of type “App” will get initiated for the queued activity execution.
• Access group of the App requestor will be the same as that of the access group of the logged-in user who queued the activity for execution.
• Control will be immediately passed to the calling activity since the queued activity execution happens in the background.

Scenario

Whenever a passport application is received, OSP Managers should be notified and the processing should continue.

Implementation

• The above requirement can be split into two smaller units. One to send notification and the other to process the request.
• The processing of requests is independent of the email notification sent. Hence this logic can be executed in parallel using the Queue method.

• Email notification is sent asynchronously using the Queue method, whereas application validation is dependent on parse information hence it’s invoked synchronously using the call method.
• Just for our POC, the Wait method is used in the queue activity to show the app requestor getting created at the back-end.

Debugging

Since Queue executes the activity in different requestors, it can’t be directly debugged using the tracer tool. Instead, we can debug using a few alternatives listed below.

• Queue method in activity can be replaced with the Call method which enables debugging using tracer tool. Once debugging is done, revert the changes made.
• We can use Log-Message method inside queued activity to print the required information in PEGA logs.

• Queue activity can be made to wait for some time interval using the “wait” method and the app requestor created at the back-end can be directly traced from the Requestor landing page.

Pointers To Remember

• Queue method can be used for executing any business transaction logic asynchronously. A few examples are sending emails, updating an external table/data type, etc.
• Queued activity runs on the context of the step page mentioned in the Queue step. Parameters passed from calling activity will be readily available in the queued activity.
• Queue method can be preferred in below scenarios
  • When business logic can be executed without any dependency.
  • When performance is a consideration.
• Queue method can only pass parameters to the queued activity but not the local variables.

We hope you have learned something new in this post. Let’s explore more on other methods in our continuation post [Part 2].

Part 2 will cover the following methods.

• Activity-Clear-Status
• Activity-End
• Activity-List-Add
• Activity-Set-Status
• Apply-DataTransform

Stay tuned for part 2 😎