Repeating steps in an activity
Use the Loop button to identify iterations, optional fields that can define an enumeration of or loop condition for this step.
Loops repeat a step or a contiguous sequence of steps a number of times, or until a
condition is met. You can iterate over the elements in an aggregate property — a
Value List
,
Value Group
,
Page List
, or
Page Group
.
This feature provides a limited form of enumeration or looping, similar to the "repeat until" or "do while" or "repeat from X to Y" structures of programming languages.
Repeating a single step using the loop field
Click the Loop button to access the details of the iteration. Use the pop-up dialog to indicate whether and how to repeat the step. You can cause the step to repeat a specific number of times, or until a specific result is reached. Click OK to save your edits and close the dialog.
Use the Repeat selection box to apply the step to more than one page or object. Select:
For each top level page
For each embedded page
For each element in value list
For each element in value group
For loop
To exit the iteration before processing all elements in the iteration, complete a transition that is true after the last desired element is processed.
When processing the
For loop
or iterating over a
Value
List
or
Page List
property, the parameter
param.pyForEachCount
holds the current iteration number. You can examine
(but not alter) this value in the step. For example, to iterate only over the first ten
pages or values, you can exit the iteration when
pyForEachCount
is greater
than 10.
For each top level page
Select the
For each top level page
option to sequence through all pages
of a specified class or classes and perform a method or instruction for each top level page.
Leave the Step Page field blank. Each time the step repeats, the step's page changes.
For the optional Only Loop for Certain Classes parameter, enter a class or classes. (Click the Add Row icon to add more than one class.)
When Only Loop for Certain Classes is not blank, iteration processing skips over any page with a class that does not appear on the list, or is not derived from one of these classes.
Use the add row icon to add a class. You can rearrange the order by selecting the row number and moving it up or down.
For each embedded page
Use
For each embedded page
option to apply a method or instruction to
each embedded page in a
Page List
or
Page Group
property.
Use the iteration choice to specify processing that is to occur for each embedded page. For
example, you can:
- Copy each embedded page
- Delete each embedded page using Page-Remove
- Delete a property on each embedded page
- Add a property to each embedded page
and so on.
Identify the property containing the embedded pages in the Target field. The SmartPrompt
list for the Target field shows only
Page List
and
Page
Group
properties.
For the optional Only Loop for Certain Classes parameter, enter a class or classes. (Click the Add Row icon o add more than one class.)
-
When Valid Classes is blank, all pages of the
Page List
orPage Group
are included in the iteration. - When Only Loop for Certain Classes is not blank, iteration processing skips over any page with a class that does not appear on the list, or is not derived from one of these classes.
For each element in a value list
Select the
For each element in value list
option to repeat the step for
each element in a
Value List
property.
Each time the step repeats, the system applies a method or instruction of your choice
(such as Property-Set) to the current property. Use the
<CURRENT>
index
value to refer to the current property element.
When you select this iteration form, a Value List Property field appears. Identify the
Value List
property in the field.
For each element in a value group
Select the
For each element in value group
option to repeat the step for
each element in a
Value Group
property.
When you select this iteration form, a Value Group Property field appears. Identify the
Value Group
property in the field.
Each time the step repeats, the system applies a method or instruction of your choice to
the current property. Use the
<CURRENT>
index value to refer to the
current property.
For loop
Select the
For loop
option to repeat the step a number of times
determined by the values of integer constants or integer properties.
Enter integer constant values or integer property references for the Minimum Value, Maximum Value, and Increment fields. The Increment must be a positive integer.
The system accesses these three values once before starting the iteration. The iteration may occur zero, one, or many times, repeating until the incremented value is greater than or equal to the stop value (unless a transition causes processing to end earlier).
Understanding
<CURRENT>
The symbolic reference
<CURRENT>
can be used only in the activity step
that defines the iteration. If that step calls another activity, the symbolic reference
<CURRENT>
cannot be used in the called activity; rather, aspects of
the current iteration are available on the parameter page of the called activity:
-
For a repeat type of
For each element in value list
orFor each element in value group
, the symbol<CURRENT>
refers to the value of ClipboardProperty corresponding to the iteration. For the called activity, this corresponds to thepyPropertyValue
parameter described below. -
For a repeat type of
For each embedded list
,<CURRENT>
refers to theClipboardPage
of the current iteration: for example, when used in an RUF call that takes aClipboardPage
parameter or on the right side of a property set when the target is a page (when you add to a page list using.list(<append>)
). -
For other repeat types,
<CURRENT>
refers to the index number of the current iteration, and corresponds to thepyForEachCount
parameter. <CURRENT>
can be used within the precondition and transition elements of a step that also includes a repeat element to evaluate the current element of the repeat.-
Within a repeat block,
<CURRENT>
can appear in the Expression Builder for the Target field of a Property-Set method; the keyword will refer to the current element’s property so that it can receive the new value.
Multistep loops
The scope of a loop can be more than one step. The loop type and conditions are set in the first step of a multistep loop.
To create a multistep loop:
- Identify the step that is to be first in the loop. Click Loop to access the pop-up dialog, and complete the loop details.
- Complete information for the first step. Identify the step page. Optionally, you can leave the method blank.
- Select the stage, open the right-click context menu, and select Add Child. The current step is renumbered as NNN.0, where NNN was the previous step number. The form changes to include a new later step NNN.1. The scope of the iteration is now both NNN.0 and NNN.1. This zero-numbered step is known as the parent step.
- Complete NNN.1, a child step. Leave the Step Page field blank and the iteration criteria blank in most cases, to have the child steps operate on the step page identified in the parent step. Optionally, you can override this step page of a child step by entering one of the following:
- a top-level page (such as the primary page).
- a reference to a page relative to the step page of the parent.
-
a reference to a
Page List
orPage Group
property on the step page of the parent. (In this case, complete theFor each embedded page
iteration details for the child step.)
- To create an iteration of more than two steps, click within the parent step NNN.0 again to make it active, and select the Add Child menu option gain.
Numbered child steps are executed in sequence NNN.0, NNN.1, NNN.2 ... then NNN.0 again, until the iteration ends or a transition causes a jump to a labeled step.
You can add addition child steps at the same level by placing the mouse pointer in the Description field and pressing the Enter key.
To convert an iteration sequence to comments, enter two slash characters // in the Label field of the parent step. The parent and all child steps become comments.
For an example of multistep and nested iterations, see the Pega Community article How to use multistep loops and nested loops in activities.
Nested iterations
By using the Add Child menu option on a child step numbered NNN.Z, you can create a nested iteration.
For example, clicking a child step numbered 14.8 converts this to 14.8.0, and inserts a second-level child step numbered 14.8.1. Complete the iteration conditions for step 14.8.0.
Use care in entering the Step Page for the parent step of a nested iteration (14.8.0 in
this example). If you refer to an aggregate property (Value Group, Value List, Page Group or
Page List), select a property that reside on the
<CURRENT>
step page of
the parent's parent. (That is, the structure of the iteration must follow the structure of
the page). Within a nested step that does not have a repeat element,
<CURRENT>
inherits the semantics of its parent step that does have a
repeat element.
Restrictions
If a step is part of an iteration sequence, the method cannot be any of the following:
Connect-Java
Obj-Open Obj-Open-By-Handle Obj-Sort |
Page-Change-Class
Page-Merge-Into Page-New Page-Validate RDB-Open |
Parameters available to called activity
The Pega Platform automatically adds the following parameters to the parameter page of a called activity with a step that contains an iteration.
pyForEachCount
— Index of the current iteration, normally starting at 1 and incrementing by one. (If the iteration type isFor loop
, the starting value may be a value other than 1 and the increment may be a value other than 1.) This parameter is available throughout the iteration as well as in called activities.pyIterationType
— Indicates the iteration type, internally represented by one of the constantspage
,embedded
,propertylist
,propertygroup
, orrepeat
. (This parameter values are not available to other methods in an iteration step.)pyIterationTarget
— Identifies the name or reference of the iteration. For page and repeat types, it is blank. For embedded, it is the step page reference. Forpropertylist
orpropertygroup
, it is the property specified in the iteration. (This parameter values are not available to other methods in an iteration step.) (This parameter values are not available to other methods in an iteration step.)pyPropertyValue
— Available only forpropertylist
andpropertygroup
iterations. The text value of the current property. (This parameter values are not available to other methods in an iteration step.)pyPropertyReference
— Obsolete. Set to "???" for backward compatibility.pyPropertyType
— Obsolete. Set to "???" for backward compatibility.
Previous topic Defining step transitions in an activity Next topic Calling an automation from an activity