An iterator is a specialized form of subdiagram that implements loops or iterations. Use an iterator to perform an operation:
An iterator can also be used as a loop. Any values required for initializing, testing, and incrementing the loop must be supplied in the Iterator Properties dialog box.
An iterator diagram can call subdiagrams or other iterators. A hierarchy of iterators is necessary to process hierarchical business objects or hierarchical business object arrays.
When execution of the parent diagram reaches the Iterator symbol, control passes to the iterator activity diagram. The collaboration repeats execution of the iterator diagram for each attribute in the business object or each business object in the business object array. You have access to the item currently in the iterator through the iterator variable specified in the Iterator Properties dialog.
After the iterator has finished executing, control passes back to the parent diagram.
To add an iterator to the activity diagram:
A unique identifier appears for the iterator in the scenario tree, hierarchically arranged under the parent diagram. The scenario tree displays the name in the following format:
(UID)
If you provide a label for the iterator, the scenario tree displays the name in the following format:
label (UID)
The UID is a unique identifier that is also the name of the iterator object in the scenario tree. As with UIDs for other symbols, you can choose whether or not to display the UID for the iterator. To turn on or off display of the UID, use the context menu on the scenarios node in the template tree.
An iterator working on attributes of a business object or an array of business objects needs to have a variable to hold the item being processed in each iteration. This iterator variable is actually a scenario variable that is created and initialized in the Scenario Definitions dialog box. Create iterator variables before defining the properties of an iterator.
If the iterator is working on the attributes of a business object, you can use an Object to hold the current attribute. For example, you might have the following declaration:
Object iterAttr = null;
If the iterator is working on business objects in an array, you can use a variable of type BusObj to hold the current business object. For example:
BusObj iterBusObj = new BusObj("LineItem");
If the iterator is being used as a loop, you do not need to create an iterator variable. The system creates one automatically during processing. The loop index variable can then be retrieved with the getCurrentLoopIndex() API.
After the iterator appears in the activity diagram, you can define its properties in the
Iterator Properties dialog box (see Figure 40).
Figure 40. Iterator Properties dialog box
Open the Iterator Properties dialog box by right-clicking the iterator and selecting Properties from its context menu. You can define the iterator's label and provide a description; both of these properties are optional. However, you must define certain other properties depending on the type of iterator you want to use. The following sections describe the requirements for defining each type of iterator.
If you want to iterate attributes of a business object, do the following:
After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each attribute it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.
If you want to iterate business objects in an array, do the following:
Use the following syntax if you type the value directly in the field:
BusinessObjectVariable.AttributeName
where BusinessObjectVariable is the name of the parent business object and AttributeName is the name of the attribute that represents the array of child business objects.
For example, to iterate through business objects in an array represented by the Items attributes in a business object contained in the variable order, type order.Items in the Iterate through this array field.
After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each business object it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.
To define a loop, do the following:
After you have defined an iterator's properties, you must edit its activity diagram to define what the iterator does for each attribute or business object it processes. Open an iterator's activity diagram by double-clicking the iterator name in the template tree view of Process Designer Express.
A break can be added to an iterator's activity diagram to force premature termination of the iteration. When the iterator's execution path reaches the break symbol, the iterator terminates and control is passed back to the parent diagram. Breaks can be used with all types of iterators.
Place a break symbol in an iterator's activity diagram as follows:
Optionally, you can add a label and description to a break symbol. Double-click the break symbol in an activity diagram to open its Break Properties dialog box and edit the properties as desired.