When to create activity rules

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:

ColumnDescription

LabelOptional. Provide an identifier for the step that can be referred to from other steps.

(Iteration)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.

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.

DescriptionEnter text that explains to other developers the action that the step is performing.

PreconditionOptional. Provide a condition or When rule that, when, based on the result, will cause the step to execute or be skipped.

Step PageOptional. Identify a Page to be used as the context for referenced properties within the step.

Expand MethodClick the button to expand the parameters for the selected method.

MethodOptional. Select the method that this step will execute.

TransitionOptional. Similar to a Precondition. After the step is executed, a condition 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. 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 . 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 ., 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.

UsageSpecify 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.

UsageIdentify 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.

UsageSimilar 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.

UsageAt 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 from the where and place them on the 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.

UsageIn 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.

UsageIn 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 Obj-Open), 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.