Logic Category

Loop over Repeating Elements with a For-Each Action

The for-each action enables you to loop over a repeating element and process one or more actions within the scope of the for-each action. The number of loop iterations is based on a user-selected repeating element. For example, you may have an integration in which you download a number of files and want to loop over the output of the files. The for-each action enables you to perform this task.

Creating a For-Each Action

Note:

You cannot use an unqualified repeating element in a for-each action.
When you configure a stop action inside a for-each action, the entire integration is terminated when the for-each action is processed for the first time. The for-each action is not allowed to process more than once. The stop action does not display any message describing this behavior during design time.

Add a for-each action to an integration in either of the following ways:
- On the right side of the canvas, click Actions and drag the For Each action to the appropriate location.
- Click at the location where you want to add the for-each action, then select For Each.
The Configure For Each panel opens. This includes a Sources tree of elements.
Click Edit under Configure For Each to enter a name and optional description for the for-each action.
Expand the Sources tree to select an element.
Drag a repeatable element to the Repeating Element field. This is the element over which to loop.
Note:
Note the following restrictions:
- The selected element must be repetitive. You can identify repetitive elements by the three-box icon to the left of the element name.
- Any parent of the selected element must not be repetitive.
- The data type of the selected element must be scalar.
- Global and nonglobal repeated elements can be selected.
- If you have a repeating element within another repeating element (that is, a list within a list), you must first create a for-each action and loop over the parent list. This gives you access to the child list during every iteration. You can then create a second for-each action within the scope of the first for-each action and loop over the child list.
For this example, the element over which to loop is ICSFile.

For every iteration of the loop, there is a single reference to the repeating element (ICSFile). A current element name file is required for this action to occur.
Enter an alias for the current file of the iteration in the Current Element Name field.

Note:
If you drag a for-each action into a schedule integration or the for-each action is not inside a while action, for-each action, scope action, and so on, an additional field called Process items in parallel is visible at the bottom of the dialog.

When selected, iterations of the for-each action are run in parallel. For example, if an integration processes a list of files with a for-each loop created over every file, the processing of the entire file is done in parallel for every file. If a variable is declared outside a for-each loop with Process items in parallel selected and updated within the for-each loop, the last updated value for that variable is available outside of the loop. Also, the degree of parallelism (DOP) is set to 1 to avoid concurrency issues.
Click Save.

The for-each action is displayed in the canvas. A looping arrow indicates that this action performs repetitive looping.
Click + inside the for-each action to add additional actions. These actions define what happens during each iteration of the loop. For this example, scope and switch actions are defined within the for-each action.

Description of the illustration oic3_for_each2.png

Using Global Variables in For-Each Loops

When global variables are used in for-each loops (for example, for logging purposes), they can lead to the following runtime exception when bad or invalid data is associated with the variable:

FORG0001: invalid value for cast/constructor, Cikey=13695578,
FlowId=10025204, Current Activity Key=13695578-BpAss43-BpSeq8.240-4, Current
Activity Label=assignment_ics_api_internal_variable23,

As a recommendation:

Limit the use of global variables in for-each loops.
Global variable handling requires database access, which results in an added performance overhead.
Local variables can be used for logic specific to a local scope.

Tracking the Status of a For-Each Action During Runtime

You can track the status of the for-each action on the Instances page through the tracking diagram and activity stream for an activated integration.

In the navigation pane, click Observability, then Instances.
Click the business identifier value of the integration to track.

The integration flow (including any for-each actions) is displayed. Any for-each action failures are identified by red arrows. The activity stream is displayed on the right side.

Route Expressions with Switch Action Branches

You can define switch action branches to add routing expressions in your integration. The switch action takes the first branch that evaluates to true. The other branches are ignored. A switch is essentially single-threaded.

Add a switch action to an integration in either of the following ways:
- On the right side of the canvas, click Actions and drag the Switch action to the appropriate location.
- Click at the location where you want to add the switch action, then select Switch.
Note:
Nested switches are supported.

Two branches are automatically created:
- Route 1 (first) branch: You must define a routing expression for this branch.
- Otherwise (second) branch: This branch is taken if the routing expression for the initial branch does not resolve to true.
Note:
To add more branches, click Actions in the switch action, then Add.
From the Route 1 branch icon, double-click the branch or click Actions , then Edit.

The Configure Route panel opens. This includes a Sources tree of elements.

You can now define different data flows for both the defined and otherwise branches in the switch action.
Click Edit under Configure Route to enter a name for the Route 1 branch.
Define a routing expression. For this example:
- filetype is dragged to the upper Value field
- = is selected as the operator
- 'json' is manually entered in the lower Value field. You can also drag a value from the Sources tree or select a value from the drop-down list.
You can add functions to your expression under the Functions tab. XPath version 2.0 functions are supported. Base 64 encode and decode functions that process data confidentially across layers and functions that return boolean results are also supported. Functions that return nonboolean values are not supported.
Click Switch to Developer Mode to view the complete path name.
Click Add condition to add more conditions or Add group to add group conditions, when needed.
Click Save.
For this example, the following expression is defined:
Drag other actions and invokes into the branches of the switch action, when required by your integration. For this example, two switch action branches are defined.

Process Tasks in Parallel with a Parallel Action

You can use a parallel action to process tasks in parallel to improve integration performance and response times. A parallel action allows the path of an integration to be split into multiple branches. Each branch is processed in parallel due to their independence from each other. Messages are sent to each service endpoint in parallel.

When all tasks are completed, all branches are automatically synchronized and merged at their termination points in the parallel action and the main path of the integration is resumed. Any variables created inside the parallel branches (for example, invoke responses) are available for use in the main path.

Want to see a video demo of the parallel action?

Use Cases

A parallel action is useful for use cases such as the following:

An order processing integration contains individual tasks for checking inventory, customer credit, and legal constraints. These tasks are processed in parallel to ensure a better response time.
An integration obtains the lowest price for an item from suppliers. The integration checks three suppliers for prices and takes the best offer. The three price checks are done in parallel because they are independent of each other. Once the three suppliers have responded, the branches are terminated. The three prices are compared to identify the lowest. The integration then continues its main path by placing the order with that supplier.
An integration processes an incoming order from both an inventory and legal perspective (for example, can the product be shipped to the customer's country). Both checks are done in parallel.

Guidelines and Restrictions

You can create a maximum of five branches to a parallel action. If you attempt to create a sixth branch by selecting Actions , and then Add on the parallel action, the selection is disabled.
There is no limit to the number of parallel actions you can include in an integration.
Synchronous and asynchronous integrations are supported.
You cannot add a parallel action inside another parallel action.
Parallel actions can be used in application integrations and schedule integrations.
Only map, scope, switch, logger, JavaScript, B2B, and notification actions and invoke connections are supported in a parallel action branch.
You can add parallel actions to the branches of a pick action.
You can add parallel actions inside scope and switch actions.
Nesting of parallel actions in for-each actions, while actions, or stage file actions with chunking is not supported.
No independent branch-specific fault handling is supported. You can catch faults at the integration level with a global fault handler.
Synchronization of global variables is not supported.
Branch-specific timeouts are not supported.

Design Time Behavior

The following example provides a high-level overview of how to design a specific parallel action. This is just one example of parallel action use.

Add a parallel action to an integration in either of the following ways:
- On the side of the canvas, click Actions and drag the Parallel action to the appropriate location.
- Click at the location where you want to add the parallel action, then select Parallel.
A parallel action with two branches is created.
Select Actions to perform the following tasks.
- Edit: Change the name of the parallel action.
- Add: Add more branches. You can add a maximum of five branches.
- Delete: Delete the parallel action.
- Collapse/Expand: Collapse or expand the parallel action.
- Cut: Cut the parallel action and paste it elsewhere in the integration. You can also cut and paste existing maps/invokes into the new parallel branches to make them process in parallel. You cannot cut an individual branch of a parallel action and paste it into another parallel action.
  See Cut and Paste Elements in the Integration Canvas.
For this example, a third branch is added.

For this example, the three branches are designed to obtain loan offers from three service endpoints and then select the best one.
Add and configure three REST Adapter connections to invoke the following service endpoints. At runtime, all three loan service endpoints are invoked in parallel to identify their specific loan offers.
- American Loan
- United Loan
- Star Loan
In the mapper for each invoke action, map your SSN to the loan application for that service endpoint.

At the bottom, the three branches are synchronized at their termination points and the parallel action rejoins the main branch of the integration. The main integration does not continue until all branches are complete
Add a switch action to define the routing rules to check for the best offer returned from the loan service endpoints.
Define the message in a log action for each switch branch.

When complete, the integration looks as follows.

The integration is now ready to be activated and invoked.

Runtime Behavior

You can view the status of parallel branches in the activity stream during runtime. For example, assume your integration is designed with the following:

One parallel action with two branches
A second parallel action with three branches

This image shows an integration with a trigger, map, invoke, a parallel action with two branches (each branch consisting of a map and an invoke), and a second parallel action with three branches (each branch consisting of an invoke). Below this is a map.

Invoke an instance of your integration and go to the Instances page.
During runtime, the activity stream shows both parallel actions and their number of branches. For this example, both parallel actions processed successfully.
Expand each branch to view more specific details.

Manage a Group of Actions and Fault Handlers with a Scope Action

You can manage a group of actions with a scope action. The scope action is essentially a collection of child actions and invokes that can have their own fault handlers. The scope action provides the behavior context for the child elements. The elements defined in the parent scope have local visibility inside this scope. Anything that you can do in an integration such as designing invokes, mappings, and actions can be done in a scope action.

Note:

Scopes can have fault handlers in which specific faults can be caught and rethrown. However, in the case of connectivity agent-based invokes, the named fault handlers are not processed. All fault handling must be done in the default fault handler.

Create a Scope Action

Add a scope action to an integration in either of the following ways:
- On the right side of the canvas, click Actions and drag the Scope action to the appropriate location.
- Click at the location where you want to add the scope action, then select Scope.
Click Edit under Edit Scope to enter a name and optional description for the scope action.
Drag and design appropriate actions, mappings, and invokes into the scope action.

The scope includes a default fault handler that is accessible by clicking the scope action and selecting Actions , then Fault Handlers, then Default Handler.
Click + to define actions on the default fault handler.
To return to the scope action, click the fault handler, and select Actions , then Show Scope Block 'scope_name'.
When you add invokes to a scope, the named faults associated with the invokes are added to the default fault handler in the scope. For example:
1. Add and configure an invoke connection inside the scope action (for example, a REST Adapter).
2. Click the scope and select Actions , then Fault Handlers.
  In addition to the Default Handler, an invoke fault handler has been added.
These are faults that the invoke can handle. The uniqueness of the named faults is defined by the qname of the fault. If there are multiple invokes that define the qname fault, the fault (at runtime) can respond to any invoke. The various invokes cannot be differentiated if their qnames are not unique.
Select appropriate named faults.

You can also define catch all blocks for fault handling through use of the raise error action in the Fault Handler section of the scope action. Catch all blocks are processed if an invoke throws a fault, but there is not a specific catch named for it. See Catch Faults with a Re-throw Fault Action.
Collapse the scope action by double-clicking it. You can expand it again by double-clicking it, selecting Actions, then Expand, or clicking >.

Note:

For application integrations with multiple REST Adapter invoke connections, only one handler can be defined when there are multiple invokes in an integration with scopes. Though the fault handler options are available for each invoke in the scope, it always points to one single handler.

Add Nested Scopes to a Scope Action

You can add nested (child) scope actions to a basic scope action. This provides a more sophisticated way of organizing or separating actions into a subsection of the integration. A nested scope provides the following capabilities:

Behaves the same way as a basic scope. It provides its own container of child actions and fault handlers.
There is no limitation to the levels of nesting. Even a scope’s fault handlers can have nested scopes.

Drag a scope inside an existing scope.
Add actions and fault handlers to the nested scope, when necessary.

Track the Status of a Scope Action During Runtime

You can track the status of the scope action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

In the navigation pane, click Observability, then Instances.
Click the business identifier value of the integration to track.

Depending upon runtime processing, several scope processing states can be displayed in the diagram:
- Scope processing succeeds and is displayed in green. Because the fault handler is not processed, the Fault Handler section of the scope remains hidden.
- Scope processing fails and is displayed in red, but the fault handler succeeds in handling the fault and is displayed in green. Processing continues after the scope. Because the fault handler was processed, the Fault Handler section of the scope is visible.
- Both the scope and fault handler fail. Both are displayed in red. Both the scope and the Fault Handler section are displayed.

See Track the Status of Integration Instances for additional details.

Rename a Scope

Open the integration that includes the scope to rename.
Click to collapse the scope action.
Click the scope and select Actions , then Edit.
Change the name and click Save.

Loop Over Actions or Invoke Connections While a Condition is Satisfied with a While Action

The while action enables you to loop over actions or invoke connections as long as a specific condition is met. You define the condition for the while loop in the Expression Builder. The while action is available in both scheduled and application integrations.

Creating a While Action

Note:

Variables used in while action statements can be of several types, including number, string, and boolean types.

Add a while action to an integration in either of the following ways:
- On the side of the canvas, click Actions and drag the While action to the appropriate location.
- Click at the location where you want to add the while action, then select While.
The Configure While panel opens. This includes a Sources tree of elements.
Click Edit under Configure While to enter a name and optional description for the while action.
Manually enter, select from the drop-down list, or drag an element from the Sources tree to the Value field. You can also add functions.
Select an operator.
Enter a value in the Value field.
Click Save.

For this example, while the counter is less than or equal to 10000, the integration loops over the condition. When the condition is not met, the looping ends.

Description of the illustration oic3_while.png
Drag invoke connections or other actions for configuration to the + sign that is displayed inside the while action. These invoke connections and actions are processed as long as the condition set in the while action is met.
If you want to edit the name or expression, double-click the While icon or select Actions , then Edit.

Note:
Deleting a while action has no impact on downstream processing of the integration because the while action does not have any output. Any changes in the upstream actions in the integration that impact the while condition result in the display of a warning icon on the while action.

Track the Status of a While Action During Runtime

During runtime, you can track the status of the while action in the Instances page through the tracking diagram and activity stream for an activated integration.

In the navigation pane, click Observability, then Instances.
Click the business identifier value of the integration to track.

The integration flow (including any while actions) is displayed. Any while action failures are identified by red.