Configuring a Loop Activity to Loop Through Documents In a Folder

Starting with KTA version 7.9 processes are failing with error message Capture Variable xxx is not initialized. Document loop behavior has changed in later KTA versions.  In the previous versions, document variable processing can be done within loop and then add decision point for more documents. Starting KTA 7.9 it must add decision point for more documents after loop and then do document variable processing.

Issue

When processing a Job, the Job suspends with the following error:

Evaluation Failed:Retry Count 1 Reason of Failure Error. Capture variable DOCUMENT is not initialized.

Note the variable mentioned in this error can be any variable.

How can a loop activity be configured to loop through documents in a folder?

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 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.