Activity Methods on Clipboard Pages
In this blog article, we will go through different activity methods that can be used on clipboard pages.
Activities are one of the most commonly used rules in Pega application execution.
Update: The activity rule methods remains the same across different Pega versions. The screenshots in this blog article were reused from Pega 7 version. Use this blog article to learn the concepts and you can try it out in the latest versions as well.
In an activity rule, we can configure sequence of steps that can executed.
Each step in an activity rule contain a method.
Activity methods can be related to exactly Java methods (that is why Pega named it as method).
So Methods are more or less like a function that can accept some input parameters and executes. Pega accommodates lot of activity methods OOTB that servers different purpose.
Also technically each method updates the pxMethodStatus property on the pxThread page. pxMethodStatus values can be – Good, Warn or Fail. This value can be used to error handle and verify if the activity method (corresponding Java function), executed successfully or ended in error.
We are going to series of Activity methods grouped under different categories.
In this article we will concentrate only on Activity methods related to Clipboard pages. Through-out this article, we will use a test activity and include the necessary methods and then use the Clipboard to test the method execution 😊
Methods related to clipboard pages
1. Page-New
Obviously creates a new page in the clipboard memory.
When do we use this method?
Let me reframe the question. When will you create a new page?
Pages can hold single value properties and can be referred in another activities and sections. When a new process starts, we can create a new page and set all the required values in the page.
For example – When we need to browse some data from a DB table and populate in the grid section.
You can use Page-New to create a new page to hold the browse results.
Note: Always remember to provide the step page in the Page & Classes tab. Else you may get activity design time error.
What are the method parameters?
a) Data transform – You can specify a data transform rule and populate the new page with required values. Not a mandatory option.
b) PageList – Don’t get confuse with the name pagelist . You need to specify a value list property here to append the Page name to the last element in the value list property.
c) NewClass – You can specify a new class for the page. The class specified here takes priority over the class specified in pages & classes tab.
For testing purpose I created a new data transform -SetLabel to set the ‘pyLabel’ = “Knowledge sharing”
Let’s test the page-new method by providing all the parameters.
Run the activity. Check the clipboard.
You can see the pxObjClass = OIKGGB-MyKnowPega ( set from NewClass method parameter)
pyLabel = “knowledge sharing” ( Set from data transform)
You can see the Valuelist property is appended with value as Step page name ( page list method parameter)
What are the things to remember when you use Page-New method?
– Always remember to mention step page in the page new method. If you forget to mention, then Page-New method clears the primary page of the activity.
– Page-new can also be considered as removing a page and creating a fresh page.
– Page name in the clipboard should always be unique. If a page with the same name already exists in the clipboard, then the Page-New method deletes the page and a new page in that same name.
– You can use an API function in any step precondition to check if the page already available in the clipboard“@PageExists(“<Page Name>, tools)” – this returns either true or false.
2. Page-Remove
This method helps in removing any existing page.
When do we use this method?
Usually we use this method to remove the pages, which are not in use.
Creating a page implies, We are using some space in JVM memory. It is always advisable, to maintain the JVM memory within limit. So obviously you need to clear out the unwanted pages.
You populated a page with required values, then you used the page and completed the process. Now you don’t need the page. You can remove it
What are the method parameters?
In the page array, you can add more than 1 page. This method helps in removing more than 1 page in a single step.
Let’s test it. Run the activity with 2 steps – Page-New & Page-Remove method.
Check in the clipboard.
Tip: Technically removing a page refers to marking the Objects for deletion. The Java garbage collection process then takes care of removing the objects from memory.
What are the things to remember when you use Page-Remove method?
In every activity, try to remove the unwanted pages in the last step
This method clears the page added in the step page field. If the step page is not specified, Page-Remove method removes only the pages specified in the method parameters page array (Never removes the primary page, when step page is blank)
If a page is not available in the clipboard, the step throws warning not error.
3. Page-Rename
This method helps in renaming any existing page in the clipboard.
When do we use this method?
There may some situation, where you need some particular data available in particular page.
For example – You have an activity which can browse and get the results in a page ‘NewPage’, but you have an section mapped to page ‘RenamePage’. In such situation, you can just rename the page.
We hardly use this method
What are the method parameters?
You have a single mandatory field – PageNewName
You enter a new page name here.
Let’s test the Page-Rename method
Run the activity and check the clipboard. You can find the new page.
What are the things to remember when you use Page-Rename method?
This method can be used only for top level page. We cannot rename an embedded page.
If the new page already exists in the clipboard, then this method deletes the existing page and create a new page
4. Page-Copy
This method helps in copying the contents from an existing page (source) into any new or existing page (destination). It’s just copying
When do we use this method?
For example – You populated a page with certain values. If you need the same values in different page, then you can use this method to make a page copy.
Note: Unlike Page-Rename method, we will have both the source page and target page available in the clipboard.
What are the method parameters?
a) CopyFrom – You can specify the Source Page here. This is not mandatory. If blank, then the step page will be the source page.
b) CopyInto – Target page.
c) Data transform – You can make use of this data transform to add some additional properties in the target page.
Note: This data transform does not update existing values. Only adds new value.
d) PageList – This parameter is same as we saw in Page-New method.
Don’t get confuse with the name pagelist :). You need to specify a value list property here to append the Page name to the last element in the value list property.
Let’s test the Page-Copy method.
Step 1: I used a property-set method and populated PhoneNumber and pyLabel values.
Step 2: In the page-copy step I set the target page as “TempPage” and use a data transform to add additional properties.
I used the same data transform used for Page-New method; pyLabel = Knowledge Sharing
Run the activity and check in the clipboard.
You can see the TempPage is created and populated with all the values.
What are the things to remember when you use Page-Copy method?
It is not always mandatory for source page and target page to be available in the clipboard.
When you use data transform, data transform rule applies first followed by page copy values.
Simply saying, you cannot update the existing values using data transform. If the destination page already exists in the clipboard, then the system deletes the old page and replace it with new values.
5. Page-Set-Messages
This method helps in adding message to the clipboard page.
We know that adding a message to a page or property, prevents the page from being saved into database.
When do we use this method?
Normally we use validate method to set the error message. You can also use other validation methods to set the error message.
In some situation, where you need to validate a single property ( no need for reusing in other areas), you can set the error message using Page-set-Messages.
What are the method parameters?
a) Page – You can provide the page name to which the error message will be added.
If left blank, then system checks step page. If step page too blank, then system adds the error message to activity primary page
b) Category – You can specify the field value category name. You use this option, when the message value is from field value rule.
c) Message – You can specify three options here
– Message rule – You can directly entry a message rule
– Field value rule – You can specify a field value rule.
Note: Field value and message rules both support localization.
– Constant string – You can also specify some hardcoded string as error message.
Let’s test the Page-Set-Messages method.
Step 1: Add a Page-Set-Messages method.
Here I have selected the 2nd option to use the field value rule –FailedToOpenInstance.
Step 2: Run the activity and check in the clipboard.
You can see the error message added to clipboard.
What are the things to remember when you use Page-Set-Messages method?
You can use this method to add error message to primary page or any embedded page.
Note: Even if you add error message to any embedded page within pyWorkPage, you cannot commit the case into db.
You can use this method in flowaction post processing activity to prevent the page from committing to DB.
Once added in flowaction post processing activity, you will see the error message displayed in UI.
Add the activity in flow action post processing – remove the step page for page-set-messages, so that error set on primary page. In our case ‘pyWorkPage’.
6. Page-Clear-Messages
This method helps in removing the property and page level messages in the step page identified.
You need to use this method with care. This method clears out all the error messages we set before.
Note: This is exactly opposite to Page-Set-Messages.
When do we use this method?
There may be some situation, where you may need to clear all the error messages before committing to database.
Note: This is not the only way system clears the error messages. System use to clear the error messages before submitting the form to server.
Say for example – You are entering a form with invalid phone number. System throws error. Now again you enter a valid number and submit the form again. Here Pega clears the error message before submitting the form.
What are the method parameters?
Cool. No method parameters 🙂
Let’s test the method.
Step 1: Add a new step: Page-Clear-Messages below Page-Set-Messages.
Step 2: Trace open the rule and run the activity.
You can see the error message set in step 2 is cleared in step 3 🙂
What are the things to remember when you use Page-Clear-Messages method?
This method not only clears the page level messages, it also clears the property level messages.
Always use this method with care.
7. Page-Change-Class
This method helps in changing the class of an existing page.
I would say Page-Change-Class = Page remove + Page – New
In addition to changing the class, you can also update some properties in the step page using data transform rule.
When do we use this method?
When we need to save/commit any existing page to some different class, we can use this method.
This method just change the pxObjClass value alone.
You can also use data transform to update some values.
What are the method parameters?
a) ObjClassNew – You can specify a new class name for the page.
b) Data transform – You can use a data transform rule to update any values in the step page.
Keep – This is an interesting parameter 🙂
– Keep – 0
Value already present in the step page are retained. Not overridden.
Eg: In step page, we have pyLabel =”Knowledge Sharing”. You cannot update pyLabel using data transform. You can just add new values from the data transform.
– Keep – 1
This is the opposite to 0. Values already present in the clipboard can be overridden by values from data transform rule.
Let’s test it.
Step 1: Create a new page ‘ActivePage’ of class – TVS-TeslaVeh-Work-ServiceRequest
Step 2: Set some values – PhoneNumber = 1111111111
Step 3: Use Page-change class method and change the class to ‘TVS-TeslaVeh-Work-SRMain’
In the data transform, update phonenumber = ‘9999999999’.
Run the activity and check in the clipboard.
Remember, we set Keep =1. So phone number updated.
You can test by setting Keep = 0
So you will get a question here!
– What do you mean by Keep = 2?
This is same as Keep=0 (retains value), with a restriction for Page list, value list and value groups.
Say, you have a pagelist property – PolicyList appended to WorkPage.
You need to change the WorkPage class and update the PolicyList property.
Let me explain it in tutorial. No words only action 😀
Step 1: Populate Active page with PolicyList page list property ( Assume 3 policylist pages)
Step 2: You need to update PolicyList with ActiveTargetPage.PolicyList values.
ActiveTargetPage – PolicyList(1) & PolicyList(2)
Step 3: Create a simple data transform and set PolicyList = ActiveTargetPage.PolicyList.
Step 4: In the page change class – Fist set Keep = 1 (Override).
Run the activity and check the clipboard.
You can see Policy list is overridden.
PolicyList(3) is removed; PolicyName = “HousePolicy”
b) Keep = 0 ( retain)
Run the activity and check the clipboard.
Check PolicyList(3)
You can see the values are retained.
c) Now Keep = 2
Run the activity and check the clipboard.
You can see the pagelist result count mismatch
ActivePage.Policy contains 3 pages.
ActiveTargetPage.PolicyList contain 2 pages.
So on updating, PolicyList(3) is updated with values from ActiveTargetPage.PolicyList(1)
You can see IsHomePolicy is copied to PolicyList(3).
In simple words, first element of the data transform list is used as the value for target list elements.
Same for value list & value group.
What are the things to remember when you use Page-Change-Class method?
Carefully set the Keep parameter, if you use data transform.
This is different from Page-Rename, where we change the page name not the class.
8. Page-Merge-Into
This method helps in merging the contents of two or more pages into one page.
When do we use this method?
When we want to bring the contents of two or more pages in a single page.
Page-Copy, copies the entire contents from source page to target page.
Page-Merge-Into, merges the contents from source page to target page with Keep parameters.
Remember keep parameter, we use for Page-Change-Class
What are the method parameters?
a) MergeFromList – You can specify more than one page using these fields. The order is significant.
Pages merge in the order they are specified in the MergeFromList array.
b) Keep – It can accepts 0, 1 or 2
Keep = 0
Contents in the source page is retained. Only new properties from target pages can be merged.
Keep = 1
Contents in the source page can be overridden. Properties from target page can update the properties in the source page.
Keep = 2
This is same as 0 with exception for PageList, ValueList and ValueGroup
You can refer the Keep parameter explanation for Page-Change-Class method. Same applies here 🙂
Let’s test the Page-Merge-Into method.
Step 1: Populate 2 source pages – TempPage1 & TempPage2 with pyLabel values.
Step 2: Populate a target page – ActivePage with pyLabel value.
Step 3: Add Page-Merge-Into step to merge the 2 source pages into target page – Active Page
Step 4: Keep = 0. Run the activity and check in the clipboard.
You can see the pyLabel value in target page is retained.
Keep =1, Run the activity and check the clipboard.
Keep = 2
If the target page list contain more elements than the source page list,
TargetPage.PolicyList – contains PolicyList(1), PolicyList(2)
SourcePage.PolicyList – Contains only PolicyList(1).
In this case, when we want to merge the page, then SourcePage.PolicyList(1) will be the source for both the elements PolicyList(1) & PolicyList(2) in TargetPage.
You can refer the Keep =2 example in Page-Change-Class method J
What are the things to remember when you use Page-Rename method?
Important point is this method cannot be used steps within iteration.
If the target page is not found, system creates a new page and merge the source pages. If the source pages are not found in the clipboard, system just ignores the source pages.
The order is some important in MergeFromList array.
9. Page-Validate
This method helps in validating all the properties within the step page
A property’s value can be restricted by using some validation in the property form.
Eg – Property mode, table type, Max length, edit validate rule.
Normally this validation occurs when you set value for the property. So why we need this method then?!
In some situation, the properties can be updated by java or some other means. In such case we can use Page-Validate method to validate all properties.
Note: Page-Validate is very expensive, since it validates all the properties within the page.
What are the method parameters?
You can see the method contains a single parameter – WithErrors
WithErrors –
Imagine the page contains error prior to this step. So if you select WithErrors, then the Page-Validate method executes and validates the properties again.
If not selected, then the method ends.
Note: You can leave this cleared, since you no need to validate a error page
What are the things to remember when you use Page-Validate method?
We use this very rarely. Keep in mind how expensive it will be, If there about 1000 proeprties within the page.
Prefer using Obj-Validate method to validate properties on a page
When a property fails validation an error message is add to the page.
These are the main activity methods that involve clipboard pages.
