Repeat actions with logic loops

You can retry actions, custom functions, and child playbooks within your playbook by creating a loop for that block, rather than adding multiple copies of the same block to a playbook. The playbook runs until it hits the looped block. The looped block runs, as described below, then the playbook continues to run. Loops are helpful in the following scenarios where, after the loop is complete, the rest of the playbook can run:

• Repeating the same action until it succeeds. For example, checking that a time-intensive process like a virus detonation has completed successfully.
• Attempting an action repeatedly, waiting between tries, until you achieve a specific result. For example, checking that a work ticket like Jira has been updated.

Logic loops allow you to retry actions, custom functions and child playbooks. This is different from looping over a parameter list. For details on looping over a parameter list, see Add custom code to your Splunk SOAR (On-premises) playbook with a custom function and Example of using a custom list in a filter.

Looping features and exit conditions

You can create loops in the following types of playbook blocks:

• Action: For details, see Add an action block to your playbook.
• Utility block/Custom function: Custom functions are called from within Utility blocks. For details on Utility blocks, see Add functionality to your playbook in using the Utility block. For additional details on custom functions, see Add custom code to your playbook with a custom function. Looping is not available for APIs called within a Utility block.
• Playbook: Looping is available for playbook blocks marked as synchronous. For details on playbook blocks and the synchronous setting, see Run other playbooks inside your playbook.

Configuring a looped block includes the following main parameters:

• The maximum number of loops to perform
• An exit condition that, if true, ends the loop
• A time-out value, to ensure a loop does not run for too long.

The parameter that occurs first determines when the loop block ends. Here are some examples of how a looped block stops running, causing the playbook to resume its flow:

• The number of loops completes before the exit condition is met, before the time-out value is reached.
• The exit condition is met before the maximum number of loops is reached, before the time-out value is reached
• The time-out value is reached before either the number of loops is completed or the exit condition is met.

Configure looping on a playbook block

To configure looping on a playbook block, follow these steps:

1. Add one of the block types listed earlier in this topic.
2. In the configuration panel, select the Configure tab and complete the information appropriate for that block. For details, see the links in the list above.
3. Select the Loop tab and switch on the Looping toggle.
4. In the Loop Configuration section, specify parameters for looping this playbook block.
   Specify how many times you want to block to repeat. This value must be between 1-99 loops. See note at the end of this section.
• If you specify a Loop Exit Condition later on the Loop tab, the block will repeat in a loop up to the number of times you specify, until the time-out value is reached, or until the exit condition is met, whichever occurs first. Default value is 2 times.
• If you do not specify a Loop Exit Condition, the playbook block will repeat up to the number of times you specify here or until the time-out value, described in Step 7, is reached.
5. Specify the amount of time you want to pause between loops. Some people refer to this as a sleep time. Recommended pause value is between 1 minutes and 4 hours. Default value is 2 minutes.
6. Specify a time-out value. Any loops not completed by that time are cancelled and, with the exception of Custom Functions, do not complete. Make sure that you allow enough time to complete the number of loops and pause times you just specified. The default value is 10 minutes. Recommended time-out value is between 1 minutes and 4 hours.
7. The following two steps are optional:
   Switch on the Loop Exit Condition toggle to specify a certain value or condition that, when true, will cause the playbook to exit this loop and move on to the next playbook block. If the exit condition is not met before the number of loops or the time-out value specified earlier on the Loop tab, the playbook will exit the loop anyway.
8. Specify the exit condition using the data path picker. For details on using the data path picker, see Specify data in your playbook. For details on condition operators, see Operators for conditions in the Use filters in your playbook to specify a subset of artifacts before further processing article.
   The configuration you specified appears in sentence form.
9. If needed, make adjustments to your configuration.
10. Select Done.

After you specify the looping configuration, the playbook block on the Visual Playbook Editor canvas displays a loop icon .

Each playbook can run a maximum of 500 actions, including each repetition of each looped block. If you anticipate your playbook will have exceed that limit, due to the number of blocks or loops, update the limit. For details, see set_action_limit in the Session automation API article.

Enforce a time-out setting for a single loop

Even if you run a playbook block a single time, you can use the time-out setting in the Loop tab to ensure that a playbook block completes within a specific amount of time. Playbook block types supported for this functionality are Action, Playbook, and Mission Control API. Custom functions are not supported, because they cannot be cancelled.

To enforce a time-out setting for a single loop, follow the instructions for looping described in the Configure looping on a playbook block section of this article, with the following changes:

• Set the Loop Configuration to loop up to 1 time, then exit.
• Specify the time-out value.
• Do not specify an exit condition.

The block will run one time and, if it is not complete by the time-out value you specify, it will be cancelled.

Loop block time-out behavior

Loop block time-out behavior is influenced by these two factors:

• Time-out settings are only evaluated at the end of an action run. The action will always complete its first run, regardless of any specified time-out value.
• The loop block time-out value is based on start time of an action processing a specific artifact, rather than on the elapsed time of running the entire loop. The loop block might run for longer than the time-out value you specify.

This illustrated example shows these how these two factors influence loop block time-out behavior. In this simple example, there is a looped action block configured with a time-out value of 60 seconds, up to 3 loops, and no delay between loops. The action is checking for user ID configuration updates.

1. The action first runs on Artifact A, that has a user ID of 100. The action block performs its first action run, completing it in 30 seconds. The first run always runs to completion.
2. At the end of the first run, the system evaluates the run time to the time-out value. Since only 30 seconds have passed, which is within the time-out value of 60 seconds, the second run is OK to begin.
3. The second run begins and takes 45 seconds, due to system latency.
4. At the end of the second run, the time is evaluated again. The total time since the action block started running is now greater than the time-out value, so the action is timed-out and cannot run a third time.
5. A new instance of the action now starts running on the next artifact, Artifact B that has a user ID of 200.
6. The action block performs its first action run, completing in 30 seconds. That run completes.
7. At the end of that first run, the time is evaluated. Since 30 seconds is still within the time-out value of 60 seconds, the second run is OK to begin.
8. The second run takes only 20 seconds, and completes.
9. At the end of the second run, the time is evaluated. The total time is still less than the time-out value, so the third run begins.
10. The third run takes 45 seconds, due to system latency, and completes successfully. This example playbook block includes only three loops, so the block exists.

In this example, although each instance of the looped action block complied with the specified 60-second time-out value, the elapsed time of the entire process was 170 seconds. This was a simple example; additional factors come into play with more complex use cases. For example, performance is affected by the number of playbook runners you have and whether the action run instances can run concurrently or sequentially. For details on performance, see the Performance implications section later in this article, and Set the concurrent action limit in Administer .

Best practices

Following is a list of some best practices for using looping in your playbooks.

• Loop over a single block, rather than adding multiple copies of the same block to your playbook.
• If you are waiting for a status, use a low number of loops with longer pauses between each loop.
• Loop over an input playbook rather than looping over multiple action blocks.

Performance implications

Looped blocks do not affect performance any differently than other playbook blocks. Looped blocks use a separate daemon process, called scheduled, that acts as a timer. The scheduled daemon process works together with the decided daemon, updating the list of pauses and delays and notifying decided when the elapsed time is complete. The scheduled daemon can wait for multiple delays simultaneously. The following sequence describes what happens when a looped block is paused.

1. When a loop is paused, the playbook runner sends a message to scheduled, requesting to restart that playbook run after the specified pause or delay.
2. The runner moves onto the next playbook run in the decided queue.
   Meanwhile, scheduled acts as a timer in the background, waiting for the specified pause or delay time to elapse.
3. When the specified time has elapsed, scheduled adds the playbook run back into the decided queue to continue the run with the next available playbook runner.

Here is an example corresponding to the figure below.

There are 4 playbook runners and 4 playbooks, 2 of which have looped blocks. All 4 playbooks are listed in the decided queue.

1. Each of the 4 playbook runners goes to the decided queue and picks up a playbook to run, based on the playbook order in the queue.
   At this point, playbook runner #1 will run the first playbook in the queue, playbook runner #2 will run the second playbook, and so on. The order will likely not be the same for the rest of the queue, because some playbooks might take longer to run than others. So the first runner of the first playbook might not be the first to complete its playbook run.
2. The playbook runners run the playbooks in parallel.
   • If the playbook does not include a loop with a delay or pause, the playbook runner completes the playbook run and returns to the decided queue to pick up the next playbook to run.
   • If the playbook includes a loop without either delay or pause, the playbook runner completes the playbook run, including the looped blocks, and returns to the decided queue to pick up the next playbook to run.
   • If the playbook includes a looped block with either a pause or delay, the playbook runner completes the playbook run until it encounters the specified pause or delay. The runner then sends a message about the pause or delay to scheduled. That runner returns to the decided queue to pick up the next playbook to run.
3. As it receives pause or delay messages from the runners, the scheduled daemon keeps track of the time for the paused or delayed looped blocks and their playbooks in the background.
4. When a playbook's pause or delay time has elapsed, scheduled adds that playbook back into the decided queue to continue the run with the next available playbook runner. These timers are all independent of one another.
5. Playbook runners continue running playbooks from the decided queue, including playbooks that were just added back to the queue after their specified delay or pause time. The runner picking up a previously paused or delayed playbook is not necessarily the runner that began that playbook run.
6. The process continues until the runners have run all of the playbooks in their entirety.

For more information on playbook runners and decided, see Run playbooks in parallel with vertical scaling and in the Administer documentation. For details on the concurrent action limit, see Set the concurrent action limit in the Administer documentation.

Loops in the datapath picker

Specifying looped blocks in the datapath picker is slightly different than specifying non-looped blocks. For details on the basics of using the datapath picker, see Specify data in your playbook.

You can specify data about the loop itself or standard data path information. Standard data path information, like the parameter artifact_id, is collected during the current loop.

Data about the loop itself includes the following loop_stateparameters:

• current_iteration: The number corresponding to the current loop iteration, between 1 and the maximum number of loops you specified.
• max_iterations: The maximum number of loops you specified.
• exit_reason: Why the loop exited. There are three possible results:
  • reached max_iterations: the total number of loops was completed
  • reached exit_condition: the exit condition was reached
  • reached max_ttl: the block reached the time-out limit
• conditions: The loop exit condition you specified. If the condition is true, the loop exits.
• start_time: The time the block began running.
• max_ttl: The time-out value you specified, after which the loop will be cancelled.
• delay_time: The length of the pause between loops.

There are two scenarios where you might specify data in a looped block. These scenarios are described in the following sections.

• Within the looped block itself
• In another playbook block that is downstream from the looped block

Specify looped block data within the same looped block

When configuring a looped block, you might refer to data about that same block when specifying the Loop exit condition. For example, you might want to exit the loop if the action taken in the block is successful. To specify data about the current looped block, follow these steps:

1. Turn on the Loop exit condition toggle.
2. Select the Select Parameter field to open the datapath picker. In the left panel, select the name of the block, for example, the action block lookup_domain or playbook block playbook_url_reputation_analysis.
3. At the top of the right panel, locate the loop-specific data paths that are added to the standard data path options.
4. Select one of the standard data path options or one of the loop_state options, as described above.
   For example, to exit the loop if the action within the loop is successful, select status. Back in the Loop exit condition panel, select the == operator, and enter success.
5. Select Done.

Specify looped block data within a different, downstream block

When configuring a playbook block that is downstream from one or more looped blocks, you might want to use data from one of the looped blocks. For example, you might configure a Filter or Decision block to use the reason the exit reason from a looped block. To specify data about a looped block earlier in the playbook, perform the standard steps for specifying a datapath.

1. When you open the datapath picker, in the left panel, select the name of the looped block, for example, the action block lookup_domain or playbook block playbook_url_reputation_analysis.
2. At the top of the right panel, locate the loop-specific data paths that are added to the standard data path options.
3. Select one of the standard data path options or one of the loop_state options, as described above.
   For example, to filter or make a decision based on a looped block's exit condition, select exit_reason. In the Conditions panel, configure your conditions, based on the possible results of the exit_reason. You might have three conditions: one for reached max_iterations, one for reached exit_condition, and one for reached max_ttl, the time-out value.