Loop step

Use the Loop step to perform a looping action in a workflow. For example, you can create a dynamic reference that returns a list of items from a data source, and then loop through items in a collection and perform one or more steps for each item in the collection. The Loop step is designed to use References to retrieve each item's values from the SmartObject when it starts each loop. When there are no more items in the reference, the loop completes.

You can use the Loop step in scenarios such as:

  • loop through a list of items in order to perform tasks on each of the items within the list
  • loop through a list of static values provided to the step
  • loop through a list of items in a reference created in the workflow
To help protect your environment from runaway workflow instances, administrators can set Workflow Step Instances Threshold policies that will force workflows to go into an Error state if too many instances of a step occurred in a specified amount of time. See the Settings topic for more information about setting these policies.

Drag the Loop step from the Logic category, Favorites bar, or the Recent category onto the canvas.

Example of a Loop step in a workflow

See the following resources for more information:

  1. From the Toolbox, click the Logic category, and then click and drag the Loop step onto the canvas.

    2. The following table explains the options available on this tab:

    Option Explanation How to Use
    List

    Specify a list to loop through. You can select a reference created within the workflow using a Create Reference step. You can also add a list of static values to loop through using a semi-colon delimiter.

    Select a referenced list from the menu.

    Select the Type/Construct my own option from the menu to create a list of static values.
    Item Reference After selecting the reference from the List menu, the current item in the loop is accessed through the Item Reference. The Item Reference shows below the selected list as a link. This link expands the Options section. Click the added item reference link to expand the Options section.
    Options Use this section to view the List Item and Index. By default, this section is not expanded. Click the down arrow to expand this section.
    List Item This is a reference to a current item in the list and automatically gets created when the list is selected. You can use this in your Loop steps to read details about the specific item being processed in the loop. Click the Edit link to change the List Item label.
    Index This field stores the current loop index. You can either create a new one or select an existing item.

    Click the Create link to create a new item.

    Click the Or Choose an existing item... link to select one.

    Click the Edit link to change the Index label.

    Click the Change link to select a different existing item.

    You use a list of customer details that needs to be updated. You create a workflow, and as the first step in the workflow, you create a reference to this list. You then add a loop function to loop through all items within the list in order to send an email containing the customer details. The loop action runs through each item in the list and populates an email with information. This action continues until it has processed the entire list.

    1. From the Toolbox, click the Basic category, and then click and drag the Create Reference step onto the canvas. Configure this step to create a reference to a SmartObject list.

      2. For more information on creating a reference, see the Create Reference step topic.

      For more information on how to use the error console, see the Error Console topic.

    2. Configure the Create Reference step and click the Create link to create the reference.
    3. From the Toolbox, click the Logic category, and then click and drag the Loop step onto the canvas.
    4. In the List section, select a reference from the menu.
    5. After you choose a reference, the new list item reference gets created for you. This list item reference is how you can access the current item being processed in the loop step, and will contain properties for the current item. To view the item reference, expand the Options section.
    6. Click the expand / collapse toggle to expand the Configuration Panel. This exposes the references for both the Create Reference step and the List Item reference created on the Loop step.
    7. Click the Create link in the Index section to store the current loop index. You can select an existing index from the Or Choose an existing item... link. If your workflow has multiple loop step configurations, you can select an existing Loop Index. At runtime the selected Loop Index is re-used. You can also select a variable, created in the Context Browser, from the Or Choose an existing item link.
    8. The Loop Index variable is created. Click the Edit link to change the Loop Index label. Click the Change link to select another index.
    9. Click the expand / collapse toggle to expand the Configuration Panel. Notice the new Loop Index variable.
    10. From the Toolbox click the Basic category, and then click and drag the Send Email step onto the canvas. Select the Send Email tab. Customize the email message by providing a subject line, additional recipients, and body of the email.

      11. See the Send Email step topic for more information about using this step.

    11. Drag a line from the Next Item port (on the Loop step) to connect it to the Send Email step.
    12. The Loop step creates two paths, namely Next Item and Complete. You need to connect the Next Item path back to the Loop step so the step can successfully loop. This action ensures that your workflow loops through the entire list.
    13. After the loop action has run through the entire list, the complete path is followed.
    14. You can add a non-outcome path to the Loop step if your workflow requires it. However, it is important to keep in mind that the activity connected to this non-outcome path fires with the Next Item outcome until the loop has completed and when the completed path is followed. In this example, a non-outcome path is added to the Loop step. After the reference is created, the Next Item path (Send Email) is followed and loops back to the step. Before the next round of the Loop step starts, the non-outcome path is followed. This means if your Loop step loops through 10 items, the non-outcome path is also followed 10 times. After all items have been looped through, the complete and the non-outcome paths are followed, which means the non-outcome path is followed a total of 11 times.

    In this example, instead of using a referenced list, you use a list of static values separated by commas. The static values in this example creates data (a list of names) in a SmartObject. This means, the loop function loops through the static values and creates a value, for each of the static values, into the specified field within the SmartObject. This action continues until it has processed all items in the static list.

    1. From the Toolbox click the Logic category, and then click and drag the Loop step onto the canvas.
    2. In the List section, select Type/Construct my own from the menu. You can also click on the Toggle button to type or construct your own list.
    3. The dynamic mode is enabled and you can create your own list. Select this option to automatically create the Items reference in the Options section.
    4. Type the static items into the List field. Ensure the values are separated by a semi-colon. In this example, type a list of names Bob; Codi; Dennis; Erica.
    5. From the Toolbox click the Basic category, and then click and drag the SmartObject Method step onto the canvas.
    6. In the SmartObject section, select the Browse option from the menu. Browse and select a SmartObject. In this example, the SmartObject (Names SmartObject) has two properties - ID and Name. The loop function loops through the static values and creates an entry, for each value, into the Name property within the SmartObject. In the Method section select Create from the menu.
    7. From the Input Mappings section, click Add and select the property. In this example, select Name.
    8. To locate the added reference, expand the Context Browser, select Fields and then expand the Reference section. Expand the Items reference, click and drag the Value field to the Input Mappings section. This creates the values, specified in the static list on the Loop step, to the Name property in the SmartObject.
    9. In this example, select the Do not map outputs radio button.
    10. Drag a line from the Next Item port (on the Loop step) to connect it to the SmartObject Method step.
    11. The Loop step creates two paths, namely Next Item and Complete. You need to connect the Next Item path back to the Loop step so the step can successfully loop. This action ensures that your workflow loops through the entire list.
    12. After the loop action has run through the static list, the complete path is followed.
    13. At runtime the workflow starts, loops through the static list and completes.
    14. Run a view on the Names SmartObject. In this example, the view is Names List View. Values from the static list created in the Name field of the SmartObject.
    15. You can add a non-outcome path to the Loop step if your workflow requires it. However, it is important to keep in mind that the activity connected to this non-outcome path fires with the Next Item outcome until the loop has completed and when the completed path is followed. In this example, a non-outcome path is added to the Loop step. After the reference is created, the Next Item path (Send Email) is followed and loops back to the step. Before the next round of the Loop step starts, the non-outcome path is followed. This means if your Loop step loops through 10 items, the non-outcome path is also followed 10 times. After all items have been looped through, the complete and the non-outcome paths are followed, which means the non-outcome path is followed a total of 11 times.
  2. With the step selected, select the Properties tab.

    3. The following table explains the options available on this tab:

    Option Explanation How to Use
    Title / Name By default, each step on the canvas has a step title. You can change this title to suit your workflow logic and show it on the canvas by checking the Show Label box. Enter a value into the Title/Name field.
    Reset link Use the link to reset any changes to the title. Click the Reset link to reset the Title/Name field to default value.
    Show Label Allows you to see the step label on the canvas. The label shows the value of the title. Check the check box to display step label on the canvas.
    Description Allows you to add a detailed description for the step. Enter a value into the Create New field.
    Notes Allows you to add additional notes for the step. Enter a value into the Notes field.
  3. Click the Errors tab.

    4. Different types of exceptions can occur on a step, such as:

    Type Description
    Known exceptions Any SmartWizard or standard wizard that has Boolean options for handling known exceptions have these options displayed as check boxes in the Known exceptions section of the Exceptions tab.
    Unhandled exceptions Any unknown runtime exceptions.

    The tab contains the following known exceptions:

    Exception Explanation How to Use
    Continue on error

    On step execution and an error occurs, continue to the next step in the workflow.

    		 Check the check box to continue if an error occurs.

    Uncheck the check box to stop workflow execution if an error occurs.

    The tab contains the following unhandled exceptions:

    Exception Explanation
    Log Exception Logs the exception to the error log.
    Force error when required SmartObject inputs are missing Will forcefully throw an error if a SmartObject method has input missing.
    Continue on error Will force the workflow to continue running the SmartObject method, even if it runs into an error.
    The exceptions in the table above is an example of those available in Workflow steps. The exceptions available depend on the Workflow step used in the design canvas.

  4. Your changes are automatically saved.

When working with the Loop step keep in mind the following considerations:

  • The Loop step requires a Reference that is based on a List method, because a List method returns multiple items. You can create the Reference in the workflow (by using the Create Reference step or any other step where you can create a Reference that uses a SmartObject list method) and select the Reference when configuring the Loop step.
  • SmartObject list methods often have input properties which you can use to filter the results returned by the method. Some list methods, for example list methods based on SQL stored procedures or REST services, may not have input properties that you can use to filter the results. However, when you select a unique SmartObject property as an identifier in a Loop step, you can use return properties to filter the results returned by the list method. For more information see Scenario 5: Creating and Using a SQL stored procedure reference with a filter in the References topic.
  • The Loop step creates two paths, namely Next Item and Complete. In order for the step to successfully loop through, you need to connect the Next Item path back to the Loop step.
  • The Complete path is followed when all items in the loop complete.
  • The Loop step cannot be added or made into a multi-step.
  • You cannot reset the loop index counter. For example, you loop through a list of five approvers. The 2nd person on the list declines. This does not reset the loop index counter. Instead, it continues to loop through the list and reaches the completed outcome.
  • See the Infinite Loop topic for considerations about potentially creating infinite loops or loops that could affect your environment when looping through large sets of data.
  • If your loop references a large list of records and the loop does not contain any asynchronous steps where the workflow pauses in the loop, be aware that you could be adding a lot of processing load to your environment while it executes the loop for each item in the loop. For example, if your loop step contains only a SmartObject step and you are looping through thousands of records in the loop, you could be adding a lot of processing load onto your environment while it processes the loop.