Action Step Type: SubAction
The SubAction action step type executes an action definition from within another action. When the sub-action has completed execution the parent action will continue. A SubAction step can execute an action once or iteratively based on various available criteria. A SubAction step is also used to execute an action in a different module.
The SubAction step type supports modularity within the actions of an application, providing for the reuse of actions that provide behaviors applicable to multiple areas of functionality. SubAction steps are also the primary means by which iterative processing can be implemented within the client application’s behavior. This step type is also the primary means of providing cross-module functionality. Using a SubAction step an action in one module may be executed from an action in another module.
A primary part of a SubAction step’s definition is the object the action it executes targets. This object should normally be within the context of the parent action’s object. As an example, if the parent action is defined for Object A, which contains a collection of Object B, the SubAction step can target an instance of Object B within that collection. The exception to this is cross-module action execution.
To execute an action across modules, the target object for the SubAction step must be an object defined in the other module. When an object from a different module is defined as the target, the actions that may be selected for the SubAction step will be those defined in that module. Execution of the parent action on the Agentry Client will then result in the action in the second module being executed as defined. The parent action will then proceed as defined after the SubAction step has completed execution.
SubAction Step Attributes
- Name: Contains the unique internal name for the step definition. This value must be unique among all steps within the same parent action.
- Execution Type: Specifies how the sub-action should be
executed. There are several options available for this attribute,
many of which providing iterative behavior. When one of these selections
is chosen, the SubAction step is referred to as a Looping SubAction
step. Lopping SubAction steps will have additional attributes that
will differ depending on how the SubAction step loops. Following
are the available items for this selection.
- Always - Execute until stopped: This selection will define the SubAction step to execute repeatedly until the user explicitly ends the processing. This item should only be selected when the SubAction executes and action that allows the user to either cancel or finish the processing, normally within a transaction wizard screen set.
- Execute Once: This selection will execute the defined action a single time when the SubAction step is executed.
- Execute once if rule is true: This selection will execute the defined action a single time only when the rule referenced in the Execution Rule attribute returns true. If the rule returns false, the defined sub-action will not be executed and the parent action will continue execution as defined.
- Execute until rule is false: This selection will execute the defined action until the rule referenced in the Execution Rule attribute returns false. This rule will be evaluated after each iteration of the sub-action. This behavior means the SubAction step will always execute the defined action at least once, as the rule will not be evaluated until after execution has completed.
- Execute while rule is true: This selection will execute the defined action while the rule referenced in the Execution Rule attribute returns true. This rule will be evaluated before the first iteration of the sub-action and before each additional iteration. This behavior means the SubAction step may or may not execute the defined action, as the rule will be evaluated to determine if the sub-action should be executed.
- Loop over collection: This selection will execute the sub-action once for each object instance referenced in the Collection attribute. This may be limited by referencing a rule in the Execution Rule attribute. In this case, the Execution Rule will be evaluated once for, and in the context of each object instance in the collection. The rule is expected to return a Boolean value. The sub-action will then only be executed for each object instance where the rule returns true.
- Loop over list screen: This selection will execute the sub-action once for each object listed in the current list screen. This may be limited by referencing a rule n the Execution Rule attribute. In this case, the Execution Rule will be evaluated once for, and in the context of each object currently displayed in the list screen. The rule is expected to return a Boolean value. The sub-action will then only be executed for each listed object instance where the rule returns true.
- Loop over selected list screen objects: This selection will execute the sub-action once for each selected object in the current list screen. This selection is provided in support of the multi-select behavior that may be enabled for list screens. If no items are selected in the list screen, the sub-action will not be executed by the SubAction step.
- Collection: This attribute is only enabled when the Execution Type is set to “Loop over collection.” The Collection attribute references the object collection property the SubAction step is to loop over.
- Execution Rule: This attribute is enabled when the Execution Type is set to “Loop over collection,” “Loop over list screen,” or to one of the execution types involving a rule. The Execution Rule references the rule definition to be evaluated to determine the execution behavior of the sub-action.
- Act on Object: This attribute references the object instance the sub-action is to target. This selection is normally a child object to the object for which the parent action is defined, or an instance of the object type for the parent object. It may also be an object defined in another module. When this last type of object is selected, the available items listed for the Actions attribute will those actions within the same module as the selected object.
- Action: This attribute references the action the SubAction step will execute as a sub-action to the step’s parent action. The action selected here must be defined prior to the definition of the SubAction step. The selected action must be defined for the object type selected in the Act on Object attribute.
- Begin Loop with Selection: When the Execution Type is set to Loop over displayed list items, this attribute is enabled allowing for the specification of the first item to be executed on. When selected, the first item is the one currently selected in the list. When not specified, the first item is the one at the beginning of the list.
- Dialog: This attribute is available only when the Execution Type is set to “Loop over collection” or “Loop over list screen.” The Dialog attribute specifies whether or not to display a message when there are no items for the SubAction to loop over. This can occur if the selected collection contains no object instances, or if the list screen currently lists no items. When Dialog is set to true, the Dialog Message attribute will be enabled allowing for the definition of the message to display.
- Dialog Message: This attribute is available only when the Dialog attribute is set to true. The Dialog Message can contain the message text to display when the item to loop over is empty. The default message displayed is “No valid records found.”
- Back Up: This attribute specifies whether to complete the SubAction step when the user clicks the Back button in a screen set displaying a transaction or fetch.
- Allow Done: This attribute specifies whether to display a Done button in last screen of a wizard screen set. The Done button differs from the standard Finish button in that the Done button will break out of the SubAction’s loop and return execution control to the parent action. When a SubAction step’s Execution Type is set to “Always - Execute until stopped,” the Allow Done attribute should be set to true. In other looping SubAction steps, the Done button will allow the user to end the loop regardless of any other constraints related to the looping behavior.