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

Description

This article describes the sample use cases for loop feature in Custom Actions and NITRO Workflows. Refer to this article for more details regarding the loop feature.

1. Update items in a list from a web service response using variable collection loop
2. Replicate assets from asset type using number loop type
3. Run send mail action for query list items using query list loop
4. Close Tickets and Ticket tasks on resolving a problem

In all sample use cases, column mappings are shown with expression builder and the old format. We can use any one of them though expression builder is the preferred option.

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

 

Use case 1: Update items in a list from a web service response using variable collection loop

In this sample use case, a custom list with title “Users” is being used to store details of the users.

‘Users’ list in SharePoint site has below columns.

Column Name	Column Type
User Id	Single line of text
First Name	Single line of text
Last Name	Single line of text
Email	Single line of text
Status	Choice (Active, Inactive)

Details:

1. Configure an invoke web service action and response of this action is stored in a variable. This variable collection will have user details like User Id, Email, First Name and Last Name
2. Web Service used in this example is a publicly available REST API: https://reqres.in/api/users
3. Response variable is then used in loop control configuration.
4. Configure a query list action in the loop body. It will query the user from ‘Users’ list based on the email address extracted from the user data in current loop iteration.
5. If user is found in the ‘Users’ list then update the details of the matching item in the ‘Users’ list.
6. Otherwise, create a new item with details of the user in the ‘Users’ list.

Custom Action

1. Define below variables
   1. VarUsers
   2. VarEmail
   3. VarCurrentUser

Action 1: GetUsers

Configure Invoke Web Service action as shown below. Please note “Define Variable Mappings” section at the bottom. Service response is in JSON format and we need to extract the values as per the structure of the JSON and put it in variables for subsequent usage.

Define variable mappings in Invoke Web Service Action:

With expression builder:

Configure the JSON path function in expression builder as shown below to extract the response from invoke web service action and update it in a variable. This expression builder uses ‘CurrentAction’ as expression type as the response of web service is available in current action.

Without expression builder:

Variable value used in above:

$jsonpath2({CurrentAction}##Value,@$.data)

Web Service Response:

Response of invoke webservice action is given below. ‘VarUsers’ variable will have the highlighted part of response as it is the extracted ‘data’ element from the response: Please note that JSON path will be different as per the response format of your API.

Action 2: Loop all users

In above Web API action response, ‘data’ element contains an array (collection) of user data. This collection was stored in variable ‘VarUsers’. We will now configure a loop control to iterate over each user in the response:

Action 3: Update VarEmail

We now want to store the email of the user in current iteration in a variable. This is done in a set variable action. These variables will be used in subsequent actions.

VarCurrentUser:

This variable is used to save the current iteration value from a variable collection.

With expression builder

Without expression builder:

Value used in the expression: $GetIterationValue(Loop all users)

Note: ‘Loop all users’ is loop control name configured in ‘Action 2’ above

Sample output:

VarEmail

This variable is used to extract the email address from above variable ‘VarCurrentUser’.

Output: george.bluth@reqres.in

With expression builder:

Without expression builder:

Variable value used in the expression below:

VarCurrentUser##email

Action 4: GetUserFromSPList

Configure a query list action to query the user from ‘Users’ list based on the email address that we have extracted in the set variable action above. Note that user with this email address may not be there in the list yet.

Value used in the condition builder:

Email equal %%VarEmail##Value%%

Action 5: Verify if user is found or not in the list

Configure gateway control to check if user is found in the ‘Users’ list. Gateway will allow us to execute different actions depending on whether user is found or not.

Value used in the condition builder: GetUserFromSPList##$count([ID|ID]),,0

Action 6: Update user record

User record already exists in the list. We will use an update item action to update the user details based on the data we got in the Web API response for user with this email Id.

With expression builder:

Expression used in the column mapping:

Property names used in above expression builder:

Column Name	Value expression
Title	id
Email	email
FirstName	first_name
LastName	last_name
Status	Active

Without expression builder:

Value expressions used in above column mappings:

Column Name	Value expression
Title	VarCurrentUser##id
Email	VarCurrentUser##email
FirstName	VarCurrentUser##first_name
LastName	VarCurrentUser##last_name
Status	Active

Action 7: Create user record

User does not exist in the ‘Users’ list. We will configure a create item action to create the user record based on the data in variable that has the user details from current loop iteration.

With expression builder:

Expression used in the column mapping:

Without expression builder:

Value expressions used in above column mappings:

Column Name	Value expression
Title	VarCurrentUser##id
Email	VarCurrentUser##email
FirstName	VarCurrentUser##first_name
LastName	VarCurrentUser##last_name
Status	Active

Use Case 2: Replicate assets from asset type using number loop type

Details:

1. This custom action uses ‘Assets’ and ‘Asset Type’ lists.
2. ‘Assets’ list has a lookup column to ‘Asset Type’ list.
3. For specified Asset Type(s), we need to create multiple assets in ‘Assets’ list.
4. This action is configured on ‘Asset Type’ list.
5. Prompt the user to enter required number of Assets that need to be created.
6. Based on the user input, create assets in the ‘Assets’ list.

This sample use case assumes that ‘Assets’ and ‘Asset Type’ lists already exist in the SharePoint site.

Below steps explain above functionality on both single and multiple ‘Asset Type’.

1. Replicate Assets – Single Asset Type
   • This action runs on single ‘Asset Type’ and creates the required number of Assets.
2. Replicate Assets – Multiple Asset Types
   • This action will query multiple ‘Asset Type’ using query list action and run the above ‘Replicate Assets – Single Asset Type’ action for each item in the result of the query list action.

Replicate Assets – Single Asset Type

Define a variable

Define a variable ‘VarNumberToReplicate’ with default value ‘0’ as shown below. This variable will be set based on the user input in next action and then used to create the specified number of assets in ‘Assets’ list.

Note: In NITRO Workflows, we cannot take the user input as they run in the backend servers, so directly specify the default user input value in variable ‘VarNumberToReplicate’.

Ex: VarNumberToReplicate = 5

Action 1: How many to replicate?

Configure execute script action to take the user input for number of assets to be created.

Note: This action is not required for NITRO Workflows. We need to specify the input for number of assets to be created directly while defining the variable ‘VarNumberToReplicate’ above.

Script:

  var NumberToReplicate = prompt(“Please enter the number of Assets to create”, “0”);

  NumberToReplicate = parseInt(NumberToReplicate);

  if (NumberToReplicate > 0){

   ccs_setwfvariablevalue(“VarNumberToReplicate”, NumberToReplicate);

  }

  else {

  ccs_setwfvariablevalue(“VarNumberToReplicate”, “0”);

  alert(“Please enter valid number”);

  }   functionCallback();

Note:

In above script, use the same name for variable as used in previous step (“VarNumberToReplicate”).

Action 2: Loop number to replicate

Configure loop control action to execute required number of times.

Action 3: Add to Assets list

Configure add list item action in the loop body to create item in ‘Assets’ list.

With expression builder (New format):

Without expression builder (Old format):

Replicate Assets – Multiple Asset Types

This custom action can be used to create multiple Assets for each of the Asset Type. This action demonstrates two levels of loop. At first level the iteration is over ‘Asset Type’ items. Then there is a nested loop to create multiple assets for the Asset Type in current iteration of outer loop.

Action 1: GetAssetTypes – Multiple

Configure query list action to get the required ‘Asset Type’ for creating assets.

Note: In this sample use case, we have configured query list action to get ‘Asset Type’ from all items list view. This query can be modified as per the requirement to fetch a subset of items.

Action 2: Run loop for Asset Type

Configure loop action with ‘Query List’ option. This is the outer loop that will be executed for each of the ‘Asset Type’ items.

Note: For all other action configurations, refer ‘Replicate Assets – Single Asset Type’ above.

Use Case 3: Run send mail action for query list items using query list loop

Details:

1. This action is configured on Tickets list.
2. Tickets list has associated tasks. ‘Associated Tasks’ list has a lookup column pointing to Tickets list.
3. Configure query list action to get open associated tasks for related Ticket.
4. Configure a loop to iterate over open tasks.
5. Send mail to assignee of the task.

This sample use case assumes that ‘Tickets’ and ‘Associated Tasks’ lists already exist and ‘Associated Tasks’ list has a lookup column to ‘Tickets’ list.

Custom Action

Define Variables

Define variables as shown below:

1. VarAssignedToEmail
2. VarAssignedToUser

Action 1: GetOpenTasks

Configure a query list action to get the open tasks for a Ticket. Conditions can be changed as per the requirement.

Value used in the condition builder:

Related Ticket ID equal ‘lookupid:%%[ID|ID]%%’

Task Status not equal Completed

Action 2: Loop query list items

Configure a loop control action for the above query list action as shown below:

Action 3: Update VarAssignedToEmail

Configure set variable action to get the ‘Assigned To’ email address from the task item. For this we first need to get the user value from the list item column. We then get the email Id of the user.

Update variables with expression builder (New format):

VarAssignedToUser

VarAssignedToEmail

Update variables without expression builder (Old format):

VarAssignedToUser:

This variable is used to save the ‘Assigned To’ column value of current iteration of query list item.

Value used in the expression:

$GetIterationValue(Loop query list items,[Assigned To|AssignedTo])

In above expression,

“Loop query list items” is loop control action name

“[Assigned To|AssignedTo]” is a ‘Assigned To’ column placeholder from associated task list.

VarAssignedToEmail:

This variable is used to save the email address of assigned to user saved in above variable ‘VarAssignedToUser’

Value used in the above expression:

$parsefieldvalue(VarAssignedToUser##Value,email)

Action 4: Send mail to assignee

Configure send mail action to notify task assignee.

Use Case 4: Close Tickets and Ticket tasks on resolving a problem

Details:

1. A problem can have multiple associated Tickets and each Ticket can have multiple associated tasks. When a problem is resolved, we need to complete the tasks of each of the associated ticket. We need to close each of these Tickets and finally resolve the problem.
2. This custom action uses below lists:
   1. Problems
   1. Tickets
   1. Associated Tasks
3. Relation between these lists is given below.
   1. Tickets list has a lookup to ‘Problems’ list.
   1. Associated Tasks list has a lookup to ‘Tickets’ list.
4. This custom action is configured on the Problems list.
5. Configure query list action to get related Tickets of the Problem on which custom action is being executed.
6. Run loop action to iterate over each of the Tickets
7. Get open associated tasks for each of the related Tickets using query list action
8. Complete all associated tasks fetched in #7. This is done with Update item action as it is a simple update process. For more complicated scenario a loop can be added here to go over each associated task.
9. Close the Ticket for loop item in #6.
10. Resolve the current Problem.

This sample use case assumes that “Problems”, “Tickets” and “Associated Tasks” lists already exist.

Custom Action

Define variable

Define a variable ‘VarCurrentTicket’ with empty value as shown below.

Action 1: GetRelatedTickets

Configure query list action to get open Tickets from the ‘Tickets’ list that are related to the current Problem.

Value used in the condition builder:

Related Problem equal ‘lookupid:%%[ID|ID]%%’

Request Status not equal ‘Closed’

Action 2: Loop all related Tickets

For each Ticket we need to do some process. So we configure a loop to iterate over each Ticket fetched in above step.

Action 3: Update VarCurrentTicket

Configure a set variable action to store the Id of the Ticket from the current iteration. This variable is used in next query list action to find all the associated tasks for the Ticket.

With expression builder (New format)

Without Expression builder (Old format)

Variable value used in the expression:

$GetIterationValue(Loop all related Tickets,[ID|ID])

Action 4: Getallopentasks

Configure a query list action to get related tasks for the current Ticket Id stored in variable ‘VarCurrentTicket’.

Values used in the condition builder:

Related Ticket ID equal lookupid:%%VarCurrentTicket##Value%%

Task Status not equal Completed

Action 5: Complete all related ticket tasks

Configure update list item action as shown below to complete all the tasks.

Action 6: Close Ticket

Configure update list item action to close the Ticket.

Action 7: Resolve problem

Configure update list item action to resolve the problem.