When to create activity rules

Activity rules provide you with one way to automate the processing of work using a
procedural, program-like approach, without requiring Java skills or manually entering
Java code. An activity is presented as a series of steps, with some of the same features as
an object-oriented programming languagesuch as iterations or conditions.
While to some who have programming experience, activities appear to be a natural,
general purpose and flexible way to create rules, activities can quickly become complex
to analyze, debug and maintain.
Accordingly, use activities only when there are no other, more appropriate rule types. For
example, instead of using a series of activity steps, use a Declare Expression rule to
calculate declaratively, rather than procedurally.
Similarly, use a when rule, decision table, map value rule, decision tree rule, or parse rule
whenever these rule types capture the business requirements well.
Even when you determine that an activity rule is appropriate, remember that Process
Commander includes dozens of useful standard activities that apply to the @baseclass,
Work-, Assign-, or History- classes. Don't create an activity in your application when you
can call a standard activity to perform the needed processing.
When writing activities, keep the following best practices in mind:

Keep activities short. Limit activities you create to fewer than 25 steps.
Limit hand-coded Java. Avoid Java steps in activities when standard rule types,
library functions, or activity methods are available. Reserve your valuable time
and Java skills for implementing things that do not already exist.

The Activity rule form

The most important tab is the Steps tab. Except as controlled by preconditions and
transitions, steps are executed in sequence, starting at step 1.
Each step contains these columns:

Column
Label

Description
Optional. Provide an identifier for the step that can be referred to from

other steps.
Optional. Loops through the elements a Value List, Page List, Value
Group or Page Group and performs the provided activity method on each
value or each embedded page.
(Iteration)
You can also create multi-step iterations using the Add Nested Step
button. For more information see How to use multistep loops and nested
loops in activities.
Enter text that explains to other developers the action that the step is
Description
performing.
Optional. Provide a condition or When rule that, when, based on the
Precondition
result, will cause the step to execute or be skipped.
Optional. Identify a Page to be used as the context for referenced
Step Page
properties within the step.
Expand
Click the button to expand the parameters for the selected method.
Method
Method
Optional. Select the method that this step will execute.
Optional. Similar to a Precondition. After the step is executed, a condition
Transition is evaluated. Based on the result, the activity may jump to another step, or
end.
The steps in an activity roughly correspond to statements in a traditional programming
language. The three control structures in activities iteration, precondition, and
transitions are intentionally limited.
At runtime, processing control can only jump to a label that is later (higher-numbered
step).
Parameters tab:
Define variables that input data to, or return data from, an activity. Parameter names and
values are held on a special page the parameter page that is not visible on the
Clipboard tool display.
Use the notation param.<ParamName> to reference a parameter value.
Pages & Classes tab:
Define pages to be used as Step Pages for the steps of the activity. Enter a page name and
associate each name with a class.
At runtime, the system uses this information to find properties that are referenced on the
Steps tab using the notation .<propertyname> where the page name is identified in the
Step Page field.. The leading period (or dot) is required.

The system also uses information on this tab to interpret property references of the form
<pagename>.<propertyname>, which may appear in various fields on the Steps tab.
Security tab:
Specify the type of activity and optionally restrict how this activity can be started. Select
the May Start? check box to allow interactive testing of the activity with the Run toolbar
button (

).

Note: The most common activity type is Utility.

Methods
Methods are individual operations that are performed in one step of an activity. This
section provides usage information on some of the most used methods. Consult the help
system in your system for additional details and descriptions of other methods.

Property-Set
Use the Property-Set method to set the value of one or more properties.
Usage
Specify the property in the PropertiesName field, and the desired value in the
PropertiesValue field.

Call
The Call method instructs the current activity to find and run another activity using Rule
Resolution. After the called activity completes, the calling activity resumes processing.
The called activity can use its own parameter page, or share the parameter page of the
calling activity. Configure this by selecting the Pass the current parameter page?
option in the method parameters.
The main advantage of being able to call an existing activity is reuse. Instead of rewriting
the called activity's steps in the calling activity, you can reference the activity.
Usage

Identify the activity you are calling by typing Call in the Method field, followed by a
space, and the activity name. For example, Call UpdateRecords. After you type or select
the method Call, you can use the SmartPrompt to select an activity.

Branch
Similar to the Call method, the Branch method refers to another activity. Execution of the
original activity ends when execution of the branched activity is complete.
Usage
Similar to the Call method.

Obj-Browse
The Obj-Browse method searches instances of one class and copies specified properties
onto the clipboard, creating a list of instances, each on an embedded page.
Usage
At a minimum, complete the PageName and ObjClass fields, along with the properties
you wish to have returned.

The field section of the method is similar to using a WHERE statement in a SQL
command. The following conditions are available for comparing properties to values.

The conditions highlighted in green do not use the Value field.

A completed Obj-Browse method is similar to a SQL statement of this form:
Select <FIELDS> from the <OBJCLASS> where <CONDITIONS = A VALUE> and
place them on the <PAGENAME> page.
Note: You can use as selection criteria only those properties that are exposed as database
columns. However, the method can retrieve values of properties that are not exposed as
columns, including embedded properties.

Obj-Open
The Obj-Open method returns a single instance stored in the PegaRULES database, or in
an external database table that is linked to an external class. The returned instance is then
converted to a clipboard page. This method differs from the Obj-Browse method by not
allowing you to define search criteria; you must identify the key of the instance.
Usage
In the OpenClass field, enter the class in which the system should start searching for the
desired instance. The search continues up through the class hierarchy until the instance is
found. Use the PropertyName and PropertyValue fields to specify the key of the instance.
If your application is to update and save the instance, check the Lock parameter to
prevent other requestors from attempting to update the same instance while your

requestor is using it.

Information from the returned instance is placed on the page listed in the Step Page field.

Page-Copy
The Page-Copy method replicates the entire contents (all properties and embedded
properties) of an existing clipboard page to a new or existing clipboard page.
Usage
In the CopyFrom and CopyInto fields, enter the page to be copied, and the destination
page, respectively.

Use the Model field to apply a model, which is located by rule resolution, to the
destination page before the page is populated with data.
Use the PageList field to save the name of the new page as the final element in a Value
List.

Page-Remove

The Page-Remove method deletes one or more named pages from the clipboard.

To remove a page, enter one ore more pages in the Page field, or enter the page in the
Step Page field.
Be sure to remove clipboard pages after they are no longer needed, to reduce system
overhead and improve performance.
Show-Page
The Show-Page method sends an XML representation of the current page (as specified in
the Step Page field) to your browser window. This method is primarily used for
debugging.

Example Activity
A simple activity can update a property for one Operator ID instance by opening the
instance, updating the clipboard page, saving the updated clipboard page, and committing
the result to the database.
Note: This simple example shows how methods work together and does not cover
security, validation, locking, error-handling, or performance considerations.
First, the activity opens copies from the database to a clipboard page one Operator
ID record, based on the value of a parameter.
Next, the activity updates the user locale, update time, and user who updated the record.
Finally, the activity saves the updated page back to the PegaRULES database, making the
updates permanent.
Each step of the activity and the corresponding method are described below.

First, define the parameters that identify the Operator ID to be updated and the new value
for Locale.
Record these parameters on the Parameters tab:

Next, on the Pages & Classes tab, enter the name of a page that can hold the contents of
the Operator ID record returned by the Obj-Open method .

On the Steps tab:

1. Add an Obj-Open method. This method opens a single record from the database,
as described above. Set criteria so that the .pyUserIdentifier property is set to the
parameter defined on the Parameters tab.

Note: In methods that return data from an object (such as Obj-Browse and ObjOpen), the returned data is placed on the page identified as the Step Page.
2. As step 2, add a Property-Set method to update the pyUseLocale property and two
other properties. Notice the Step Page is listed again. This provides context for the
properties that are selected, eliminating the need identify the page before the
period that preceeds the property name.

Note: @CurrentDateTime() is a standard function rule that returns the current

system date and time.
3. Next, save the updated record and commit it to the database using two separate
methods.
Note: For activities used in flow processing, do not include a Commit method
step. Built-in activities contain Commit methods at the appropriate places..
4. In Step 5, remove the Operator page from the clipboard (to free up memory no
longer needed) by adding a Page-Remove method. In the Step Page field, identify
the name of the page to be removed.

At this point, you can test the activity. Updated data can be seen on the Operator ID rule
form.
However, to aid in testing, it is helpful to include a Show-Page method to display the
Operator page contents before or after the Property-Set step.
Testing the Example
To test the activity:
1. Click the Run icon on the toolbar. You are prompted to enter values for each
parameter.
2. Notice the parameter names; these are the names you defined on the Parameters
tab.
3. Enter a value for each parameter.
4. Click the Execute button to start the activity.

When the processing reaches the Show-Page step, the page contents appear as an XML
document in a browser window.
The page output appears as:

Notice the updated pyUserIdentifier and pyUseLocale values.

For more complex activities, the Clipboard tool and Tracer tool are valuable debugging
aids.