Question / Problem:
How can a loop activity be configured to loop through documents in a folder?
Answer / Solution:
A common use case for a Loop activity is to loop through a folder of documents. This allows the process to assign a document variable which can be used for many API calls or other activities. The help topic Configure a Loop activity explains the basics, however it can be helpful to see a more specific and more detailed example.
The variable types used in this example are shown here for reference:
The basic structure of a loop is shown in this example:
- “Loop Docs” - The loop activity itself.
- “Doc Found (Continue Loop)” - A decision activity to decide whether to exit the loop or continue the next iteration
- “Placeholder” - This would be where to add any activity or activities that should be performed inside the loop. The last activity in the loop should connect back to the loop activity.
Loop Activity Configuration
The loop activity configuration is shown below.
- Complex variable
- The loop activity will loop over the elements of this. In this example, the Documents property of the Folder variable is used.
- Current/Updated index
- In most use cases, as with this example, the same variable will be used for both Current index and Updated index.
- When the same variable is used for both, then the loop activity handles incrementing the value.
- Separate variables might be used when there is a need for more complex increment logic, which is rare. In this case, the variable set for “Updated index” is what gets incremented in a loop iteration, but custom logic in the process would need to set this or some other index number back to the variable used for “Current index”
- It is important to note that while developers may be used to starting at index 0, here it is expected to start at index 1.
- Row found
- This is a boolean that the loop activity sets so the process knows whether the loop should continue.
- In most use cases, this will be used in a decision activity immediately after the loop activity.
- Number of columns/Variable members
- In a simple example such as this one, the current document is the only object returned in a loop iteration, so the result has only one “column.” Set the value to 1 and then click “Set columns” to allow the Variable members to be mapped. The sole column is mapped to a document variable.
- If the object returned in each loop iteration was an array or something similar, then multiple columns might be used to get each element.
Usually the same variable is used for Current index and Updated index. If different variables are used, then you are responsible for incrementing the Current index variable before the next loop. If you do not, then an infinite loop will occur. In KTA 7.5 and higher there is a Maxium Loop Count in System Settings that defaults to 1000, and will cause an infinite loop to suspend. In earlier versions you will need to manually terminate any job created with this configuration.
The decision activity simply uses the RowFound variable in the Condition text. That way if no row is found, the loop will exit.
It is recommended to always use the Row found variable from the Loop activity, which means the loop exits when finished iterating over the items in the complex variable in the loop activity. If using something other than the Row found variable from the loop activity, then the length of your loop depends on the custom logic you are using. Mistakes here can easily lead to an infinite loop. In KTA 7.5 and higher there is a Maxium Loop Count in System Settings that defaults to 1000, and will cause an infinite loop to suspend. In earlier versions you will need to manually terminate any job created with this configuration.