Applies to: NITRO activated sites in SharePoint Online and On-Premises (2013/2016/2019)

Introduction

Loop action is supported in Custom Actions and NITRO Workflows designer experience. Loop action is used to repeat a step for specific number of times.

Below loop options are supported in loop control in Custom Actions and NITRO Workflows.

1. Date
2. Number
3. Query List
4. Variable Collection

To configure loop control in Custom Actions and NITRO workflow.

Custom actions:

Go to custom actions -> Select new custom action -> Expand Events and Controls -> Drag and drop loop control on designer.

NITRO Workflows:

Go to NITRO Workflows -> Select new workflow -> Expand Events and Controls -> Drag and drop loop control on designer.

Loop Control Settings

There should always be two or more incoming connections and two outgoing connections from loop control body.

One or more connections should be back to the loop control.

Sample loop configuration:

For below sample configurations, there are two outgoing connections and two incoming connections and one of the incoming connection is connecting back to the loop control. Summary of these connections:

• Incoming:
  • Connection from a node outside of the loop to start the loop execution
    • Note: There can be multiple nodes from which loop can be initiated
  • Connection from loop body back to loop for repeated steps
    • Note: There can be more than one connections from loop body back to loop control. For example, there can be a gateway inside the loop that decides to continue loop execution or go back to loop control for next iteration.
• Outgoing:
  • Connection to the loop body to execute each step
  • Connection to a node outside of loop to exit the loop

Note: In this document, column mappings are configured in below ways in sample use cases and examples. We can use any one of the below expressions.

1. Without expression builder (Old format)
2. With expression builder (New format)
   1. Expression builder is released for Custom Actions.
   1. For NITRO Workflows, expression builder will be released soon.

Different types of loops

Loop Type: Number

Use this loop type to iterate the execution for a fixed number of times. We can specify the range using ‘Start Number’ and ‘End Number’ in the loop control settings.

Start Number: Specify the number from which we want to start the loop execution.

End Number: Specify the number at which we want to stop the loop execution.

Increment: Specify the increment value to increase the number in each iteration.

Note:

1. End Number should be greater than Start Number

Number loop type does not support decimal values in Start Number and End Number.

Supported values in Start Number and End Number:

Placeholder	Example/Scenario
Fixed values	Start Number: 1 End Number: 5
[Column Display Name|Column Internal Name]	Specify ‘Start Number’ and ‘End Number’ from the current list item column placeholder on which the Custom Action/Workflow is running Ex: [Count|Count]
Variables	Select the start and end numbers from variables. VarStartNumber##Value
Query list action name##[Column Display Name|Column Internal Name]	To use query list item placeholder, Query list action result should be a single item (not an item collection) Ex: GetConfiguration##[Start Number|StartNumber]

Sample loop control configuration for Number type:

In this sample configuration, we have used static numbers for ‘Start Number’ and ‘End Number’ in the loop configurations.

As per the below screenshot, it will iterate the execution for 5 times as the start number starts from 1 and on each iteration start number will increment by 1.

Functions Used to get values from Number Loop Control:

We can get the loop control values like current index number, start number, end number and Increment value using below function.

Function:

Syntax 1:

• $GetIterationValue(Loop Control Name)
• $GetIterationValue(Loop Control Name, parameter)

Function: $GetIterationValue(Loop Control Name)

This function will return the current iteration value of the loop.

Ex: $GetIterationValue(Run loop for number type)

As per the above sample loop configuration,

1. ‘Run loop for number type’ is the name of the loop control
2. It will iterate the loop body 5 times starting from value ‘1’
3. Output: For first iteration current value will be 1, for second iteration current value will be 2 and so on.

Supported parameters for number type loop:

1. currentindex
2. startNumber
3. endNumber
4. increment

currentindex

This parameter will return the current iteration number from the loop when it is executing.

Ex: $GetIterationValue(Run loop for number type, currentindex)

Output: For first iteration current index value will be 1, for second iteration current index value will be 2 and so on. Note that in case of number loop with starting value and increment as 1, index will be same as loop iteration value.

startNumber

This parameter will return the ‘Start Number’ from the loop control configuration. This value does not change with loop execution.

Ex: $GetIterationValue(Run loop for number type,startNumber)

Output: 0

endNumber

This parameter will return the ‘End Number’ from the loop control configuration. This value does not change with loop execution.

Ex: $GetIterationValue(Run loop for number type,startNumber)

Output: 5

increment

This parameter will return the ‘Increment’ from the loop control configuration. This value does not change with loop execution.

Ex: $GetIterationValue(Run loop for number type, increment)

Output: 1

Loop configuration with variables and functions

• Start Number: VarStartNumber##Value
• End Number: $add(VarStartNumber##Value,5)
• Increment: 1

In this loop configuration, “VarStartNumber” is a variable in Custom Actions

Loop Type: Date

Use this loop type to iterate the execution based on a date range. We can specify the ‘Start Date’ and ‘End Date’ in the loop control settings.

Start Date: Specify the start date from where we want to start the loop execution.

End Date: Specify the end date to stop the loop execution.

Note: End Date should be greater than Start Date

Increment: Specify the increment number to increase the start date in each iteration.

Unit: Specify the unit for the increment. Supported below different type of units. Increment will be calculated based on the selected unit type.

1. Day
2. Week
3. Month

Supported values in Start Date and End Date:

Placeholder	Example/Scenario
Fixed values	Specify fixed date in below format. Syntax: Month/Date/Year Start Date: 7/20/2022 End Date: 7/30/2022
Contextual placeholders	{Today} {Now} {UtcNow}
[Column Display Name|Column Internal Name]	Specify ‘Start Date’ and ‘End Date’ from the current list item column placeholders on which the Custom Action/Workflow is running Ex: [Start Date|StartDate]
Variables	Select the ‘Start Date’ and ‘End Date’ from a variable. VarStartDate##Value
Query list action name##[Column Display Name|Column Internal Name]	To use query list item column placeholder, Query list action result should be single item.   Query list action should return single item Ex: GetConfiguration##[Start Number|StartNumber]

Case 1: Loop configuration with column placeholders and increment value by ‘Day’.

• Start Date: {Today}
• End Date: [Due Date|DueDate1]
• Increment: 1
• Unit: Day

Suppose below values for the placeholders:

Start Date: 08/01/2022

End Date: 08/05/2022

Increment: 1

Unit: Day

The above loop will run for 5 times as we are incrementing the start date value by 1 day in each iteration.

Case 2: Loop configuration with variables and functions and increment value by ‘Week’

• Start Date: VarStartDate##Value
• End Date: $calcdate({Today},4, Months)
• Increment: 4
• Unit: Week

Assume below values for the dates for above configuration:

Start Date: 07/05/2022

End Date: 11/05/2022

Increment: 4

Unit: Week

Then the above loop configuration will run 5 times. This Loop will increment start date by 4 weeks in each iteration.

Functions Used to get values from Date Loop Control:

We can get the loop control values like current index number, start date, end date and Increment value using below function.

Function:

Syntax:

• $GetIterationValue(Loop Control Name)
• $GetIterationValue(Loop Control Name, parameter)

For example, loop configurations are like below, then using ‘GetIterationValue’, we can get the output as given below:

• Start Date: 07/05/2022
• End Date: 11/05/2022
• Increment: 4
• Unit: Week

Function: $GetIterationValue(Loop Control Name)

This function will return the current loop value.

Ex: $GetIterationValue(Run loop for date type)

In this example ‘Run loop for date type’ is an action name of the loop control

Output:

• 1^st Iteration: 7/05/2022
• 2^nd Iteration: 8/2/2022
• 3^rd Iteration: 8/30/2022
• 4^th Iteration: 9/27/2022
• 5^th Iteration: 10/25/2022

Supported parameters in above function for date type loop:

currentindex

This parameter will return the current iteration number from the loop when it is executing.

Ex: $GetIterationValue(Loop Control Name, currentindex)

As per the above example, this loop configuration will run for 5 times and in each iteration, we will get currentindex value. For first iteration current index value will be 1, for 2^nd iteration current index value will be 2 and so on.

startDate

This parameter will return the ‘Start Date’ of the loop control configuration.

Ex: $GetIterationValue(Loop Control Name,startDate)

Output: 07/05/2022

endDate

This parameter will return the ‘End Date’ of the loop control configuration.

Ex: $GetIterationValue(Loop Control Name,endDate)

Output: 11/05/2022

increment

This parameter will return the ‘Increment’ of the loop control configuration.

Ex: $GetIterationValue(Loop Control Name, increment)

Output: 4

Loop Type: Query List

Use this loop type to iterate the execution for each item in the result of a query list action. We can configure the query list loop type for single item and multiple items.

In this sample use case, we have configured a query list action ‘QLGetOpenTasks’

Query list action:

Query list loop configuration:

Example for Query loop type:

Clone associated Ticket tasks and send mail to new task assignee.

1. This custom action is configured on Tickets list
2. Tickets list has related tasks i.e., ‘Associated Tasks’ list has a lookup column ‘Related Ticket ID’ pointing to ‘Tickets’ list. This way, one Ticket can have multiple tasks.
3. For Ticket, get open tasks assigned to a particular user with a query list action.
4. Create a copy of each task returned in above query list action and assign to a different user.
5. Send an email to the new task assignee for each task
6. Cancel the original tasks returned in query list action.

Custom Action

Define variable

Define variable: VarAssignee

Action 1: QLGetOpenTasks

This action will get all open tasks assigned to a particular user.

Action 2: Run loop for query list items

This action will loop query list items

Action 3: Copy associated task

This action will create a copy of each task returned in above query list action and assign to a different user.

With expression builder:

Column mappings:

Without expression builder:

Column mappings:

 

Column Name	Value expression
Task Name	$GetIterationValue(Run loop for query list items,[Task Name|Title])
Assigned To	[Department::Owner|Department::Owner]
Due Date	$GetIterationValue(Run loop for query list items,[Due Date|DueDate])
Description	$GetIterationValue(Run loop for query list items,[Description|Body])
Type of Request	$GetIterationValue(Run loop for query list items,[Type Of Request|TypeOfRequest])
Related Ticket ID	[ID|ID]

Action 4: Update assignee email

With expression builder (New format):

Without expression builder (Old format):

Value expression:

$parsefieldvalue(Copy task##[Assigned To|AssignedTo],email)

Action 5: Send mail to assignee

This action will send an email to the new task assignee for each task

Action 6: Cancel open associated task

This action will cancel the original tasks returned in query list action.

With expression builder (New format):

Without expression builder (Od format):

Functions used to get values from Query loop control

We can get the loop control values using below function.

Function:

Syntax:

• $GetIterationValue(Loop Control Name)
• $GetIterationValue(Loop Control Name, parameter)

 

Function: $GetIterationValue(Loop Control Name)

This function will return the current loop item id from the QL items

Ex: $GetIterationValue(Run loop for query list items)

Output:

As per the above example, if query list action returns 5 tasks and the item ids are below:

Task Ids: 10,11,12,13 and 14

Then using this function in column mappings will return the current loop item id as given below:

• 1^st iteration: 10
• 2^nd iteration: 11
• 3^rd iteration: 12
• 4^th iteration: 13
• 5^th iteration: 14

Supported parameters in above function for Query type loop:

1. currentindex
2. endindex
3. Column placeholder of the query list item

currentindex

This parameter will return the current iteration number from the loop when it is executing.

Ex: $GetIterationValue(Run loop for query list items, currentindex)

As per the above example, this loop configuration will run for 5 times and in each iteration, we will get currentindex value. For first iteration current index value will be 1, for 2nd iteration current index value will be 2 and so on.

endindex

This parameter will return the last index of the query list action result.

Ex: $GetIterationValue(Run loop for query list items,endindex)

Output: 5

Column placeholder of the query list item

This parameter will return the current loop item column value

Ex: $GetIterationValue(Run loop for query list items,[Type Of Request|TypeOfRequest])

Output: New Request

Note: As per above example, ‘Type of Request’ column value will get from the loop item.

Loop Type: Variable Collection

We can use variables to save the column values and use them in required actions in Custom Actions and NITRO workflows.

For example, here we have defined a variable with name ‘VarallUsers’. It is assigned the value from ‘Assigned Staff’ column on the item. ‘Assigned Staff’ is a multi-selection enabled person or group column. After this value is assigned, variable ‘VarallUsers’ will have a ‘collection’ of all users who are there in the ‘Assigned Staff’ column on the item.

Use ‘Variable Collection’ loop type to iterate the execution for each value in variable collection. See the sample use case below on how to use variable collection in loop control

Example for variable collection

In this example custom action, a task is created for each user in a multi-selection enabled person or group column.

1. This action is configured on Tickets list
2. Tickets list has a ‘Assigned Staff’ column which is a multi-selection enabled person or group column
3. Store ‘Assigned Staff’ column value in a variable
4. Run loop action on a variable having collection of users
5. Create task for each user in above variable.

Custom Action

Define variable

Define variable ‘VarallUsers’ as shown below: [Assigned Staff|AssignedStaff]

With expression builder (New format):

Action 1: Run loop for all users

Run loop for above variable ‘VarallUsers’ collection as shown below.

Action 2: Create task for user

This action will create task for each user in variable collection

With expression builder (New format):

Assigned To column mapping:

Without expression builder (Old format):

Column mapping used for Assigned To column in below: $GetIterationValue(Run loop for all users)

Functions used to get values from variable collection loop control

We can get the loop control values using below function.

Function:

Syntax:

• $GetIterationValue(Loop Control Name)
• $GetIterationValue(Loop Control Name,parameter)

Function: $GetIterationValue(Loop Control Name)

This function will get the current loop value.

Ex: $GetIterationValue(Run loop for all users)

As per the above example, ‘Assigned Staff’ column having below users. This ‘Assigned Staff’ column value will be stored as a collection of users in a variable ‘VarallUsers’.

• James Restivo
• Scott Restivo
• Ryan

Output: This function will return the each of the user details in a variable collection.

• 1^st iteration: James Restivo
• 2^nd Iteration: Scott Restivo
• 3^rd Iteration: Ryan

Supported parameters for variable collection loop type:

1. currentindex
2. endindex

currentindex

This parameter will return the current iteration number from the variable collection loop when it is executing.

Ex: $GetIterationValue(Run loop for all users, currentindex)

Output:

As per the above example, this loop configuration will run for 3 times and in each iteration, we will get currentindex value. For first iteration current index value will be 1, for 2nd iteration current index value will be 2 and so on.

endindex

This parameter will return the last index of the variable collection.

Ex: $GetIterationValue(Run loop for all users,endindex)

Output: 3

 

Refer to this article for more sample use cases for loop feature.