Table of Contents

Introduction to activities

Activity rules are one way to automate the processing of work by 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 features of an object-oriented programming language, such as iterations and conditions.

If you have programming experience, activities appear to be a natural and flexible way to create rules; however, activities can quickly become complex to analyze, debug, and maintain. 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.

If you decide that an activity rule is appropriate, review the standard activities that Pega Platform™ includes. These activities apply to the @baseclass, Work-, Assign-, and History- classes. When possible, call a standard activity and avoid writing custom activities.

When you write activities, keep the following best practices in mind:

  • Keep activities short. Limit your activities to fewer than 25 steps.
  • Limit hand-coded Java. Avoid Java steps in activities when standard or custom rule types, library functions, or activity methods are available.

The following sections describe the activity rule form, methods, and give an example activity:

The activity rule form

The main tab on the activity rule form is the Steps tab. Steps are performed in sequence starting at step 1, unless you define conditions for skipping steps.

Each step contains the columns shown below:

Thumbnail

The Steps tab 

Column Description
Label Optional. Provide an identifier for the step that can be referred to from other steps.
Loop

Optional. Loops through the elements of a value list, page list, value group, or page group and performs the provided activity method on each value or each embedded page.

If you define a loop, you can also create nested (child) steps.  To add a nested step, right-click the step number and click Add child.

When Optional. Before the step is run, a condition is evaluated.  Based on the result, the step is either performed or skipped.
(Expand method) After you enter the Method, click the button to enter the method parameters.
Method Optional. Select the method that this step will perform.
Step page Optional. Identify a page to be used as the context for referenced properties within the step.  Define the page on the Pages & Classes tab.
Description Enter text that explains to other developers the action that the step is performing.
Jump Optional. After the step is run, a condition is evaluated. Based on the result, the activity can jump ahead to a higher-numbered 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 transition — are intentionally limited.

Parameters tab

Define variables that input data to, or return data from, an activity. Parameter names and values are held on a special clipboard page, known as the parameter page, which is not visible with the Clipboard tool.

Use the notation param.<ParamName> to reference a parameter value.

Pages & Classes tab

Define the 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 run time, the system uses this information to find properties that are referenced on the Steps tab by 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 might appear in various fields on the Steps tab.

Security tab

Specify the type of activity and optionally restrict how this activity can be started. 

Note: The most common activity type is Utility.

Methods

A method is an operation that is performed in one step of an activity. This section describes some frequently used methods. For additional details and descriptions of other methods, see Methods and instructions by name.

Property-Set

The Property-Set method sets the value of one or more properties.

Usage

Specify the property in the PropertiesName field and the desired value in the PropertiesValue field.  Click Add item to enter more properties.

Call

The Call method instructs the current activity to find and run another activity by 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 current parameter page check box in the method parameters.

The main advantage of calling an activity is reuse. You can reference the activity and call it from other rules instead of including all the steps in one 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 press the Down Arrow key to select an activity.

Branch

Similar to the Call method, the Branch method runs another activity. The original activity ends when the branched activity is complete.

Usage

The usage of the Branch method is similar to the Call method.

Obj-Browse

The Obj-Browse method searches for 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, and in the Field field, specify the properties to return or to use as filters.  Click Add item to add more fields.

Thumbnail

Obj-Browse parameters

The Condition value (other than Value Only) filters the records that are returned, similar to using a WHERE statement in an SQL command. The following conditions are available. 

Thumbnail

Obj-Browse conditions

The conditions highlighted in yellow do not need an entry in the Value field.  For other conditions, enter a property name or a regular expression in the Value field. 

A completed Obj-Browse method is similar to an SQL statement of this form:

 Select <FIELDS> from the <OBJCLASS> where <CONDITIONS = A VALUE> and place them on the <PAGENAME> page.

Note: Filter fields must be exposed as database columns. However, the method can retrieve values of properties that are not exposed, including embedded properties.

Obj-Open

The Obj-Open method returns a single instance that is stored in the Pega Platform database or in an external database table that is linked to an external class. The returned instance is converted to a clipboard page. This method differs from the Obj-Browse method because it does not use search conditions; it requires you to identify the key of the instance.

Usage

In the OpenClass field, enter the name of the class where the system should start searching for the 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.  Click Add item to specify more key property names and values.

If your application updates and saves the instance, select the Lock check box to prevent other requestors from updating the instance while your requestor is using it.

Thumbnail

Obj-Open parameters

Data from the returned instance is placed on the Step page.

Page-Copy

The Page-Copy method copies the entire contents (all properties and embedded properties) of an existing clipboard page to a new or existing clipboard page.

Usage

In the CopyFrom field, enter the name of the page to be copied.  In the CopyInto field, enter the destination page.

Thumbnail

Page-Copy parameters

You can apply a model to the destination page before the page is populated with data by entering a value in the Data Transform field. Rule resolution finds the model.

You can save the name of the new page as the final element in a value list by entering the list name in the PageList field.

Page-Remove

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

Thumbnail

Page-Remove parameters

To remove a page, enter one or more page names in the Page field, or enter the page name in the Step page field.

To reduce system overhead and improve performance, remove clipboard pages when they are no longer needed.

Show-Page

The Show-Page method sends an XML representation of the Step page 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. This example shows how methods work together and does not cover security, validation, locking, error handling, or performance considerations.

First, the activity opens an Operator ID record, based on the value of a parameter, and copies the data from the database to a clipboard page. Next, the activity updates the user locale, update time, and name of the user who updated the record. Finally, the activity saves the updated page back to the Pega Platform database, making the updates permanent.

Each step of the activity and its corresponding method are described below.

  1. On the Parameters tab, define the parameters that identify the Operator ID to be updated and the new locale value.
    Thumbnail
    Parameters tab
     
  2. On the Pages & Classes tab, enter the name of a page that holds the contents of the Operator ID record that is returned by the Obj-Open method.
    Thumbnail
    Pages & Classes tab
     
  3. On the Steps tab, do the following.
    1. Add an Obj-Open method. This method opens a single record from the database and copies it to a clipboard page. Enter the values shown below to specify that the value of the .pyUserIdentifier property on the Operator record equals the value of the parameter that is defined on the Parameters tab.
      Thumbnail
      Example: Obj-Open

      Note: Methods that return data from an object (such as Obj-Browse and Obj-Open) put the returned data on the Step page.
       
    2. Add a Property-Set method to update the pyUseLocale property and two other properties. List the Step page again. This provides context for the properties that are selected so you do not need to provide the page name before the period that precedes the property name.
      Thumbnail
      Example: Property-Set

      Note:  @CurrentDateTime() is a standard function rule that returns the current system date and time.
       
    3. Save the updated record and commit it to the database using two separate methods.
      Thumbnail
      Example: Obj-Save and Commit

      Note: For activities that are used in flow processing, do not include a Commit step. Built-in activities contain Commit methods at the appropriate places.
       
    4. Remove the Operator page from the clipboard by adding a Page-Remove method. This frees up memory that is no longer needed.  In the Step page field, enter the name of the page to be removed.
      Thumbnail
      Example: Page-Remove

At this point, you can test the activity. After you run the activity, you can see the updated data on the Operator ID rule form.  To help with testing, include a Show-Page method to display the Operator page contents before or after the Property-Set step.

Thumbnail

Example: Show-Page

Testing the example

To test the activity, do the following steps:

  1. Click Actions > Run.
  2. Notice the parameter names; these are the names that you defined on the Parameters tab.
  3. Enter a value for each parameter.
  4. Click Run to start the activity.
Thumbnail

Run parameters

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 shown below. Notice the pyUserIdentifier and the updated pyUseLocale values.

Thumbnail

Show-Page output

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

Suggest Edit

87% found this useful

Have a question? Get answers now.

Visit the Collaboration Center to ask questions, engage in discussions, share ideas, and help others.