FileIterator node

Use the FileIterator node to iterate over a list of files that are produced by the FileExists node, propagating one file at a time, so that it can be processed by the FileRead node.

This topic contains the following sections:

Purpose

You can use the FileIterator node along with the ListMode capability of the FileExists node. When the FileExists detects multiple files, it propagates a list of these files in the LocalEnvironment. A FileIterator node processes this list and for each entry propagates a LocalEnvironment that is compatible with the FileRead node for that specific file. The FileIterator node allows each file to be processed one at a time. If an exception occurs for a particular propagation, the exception is stored, and the remaining file entries are processed to completion.

The FileIterator node is contained in the File drawer of the palette, and is represented in the IBM® App Connect Enterprise Toolkit by the following icon:

FileExists node icon

The FileIterator node propagates to the "out" terminal for every File entry in the LocalEnvironment.Files folder that it receives. Therefore, the "out" terminal is propagated to multiple times when multiple files are listed in the input LocalEnvironment.File folder. If the source FileExists node does not have ListMode selected, then the FileIterator node receives a LocalEnvironment.File folder. In this case, the single file is propagated to the out terminal. When the FileIterator node propagates to the "out" terminal, it includes a LocalEnvironment.Destination.File record with the details of the current file. The elements in LocalEnvironment.Destination.File are shown in the following table.

Element Name	Element Data Type	Description
Directory	CHARACTER	The input directory that was specified on the FileExists node. If it was blank, it will not be included in the Destination.File record, and any FileRead node will use the directory specified in its own properties.
Remote.ServerDirectory	CHARACTER	The ServerDirectory field that was specified on the FileExists node so that it can be used by the FileRead node.
Remote.Server	CHARACTER	The Server field that was specified on the FileExists node so that it can be used by the FileRead node.
Name	CHARACTER	File name and extension.
LastModified	TIMESTAMP	Date and time the file was last modified.
TimeStamp	CHARACTER	Date and time, in the Coordinated Universal Time (UTC) zone, the FileExists node detects the file as a character string.
IsEmpty	BOOLEAN	Whether the file that is propagated by the message flow is empty. IsEmpty is set to TRUE if the current file is empty.
ProcessedBy	CHARACTER	The name of the FileExists node that detected the file.
NumberInList	INTEGER	The number of this entry in the list of files.
TotalInList	INTEGER	The total number of files in the list of files.

The FromFTP field propagated by the FileExists node is not included in the LocalEnvironment.Destination.File record. The inclusion of the Server and ServerDirectory fields indicates that the file is on an FTP server. No other LocalEnvironment fields can be overridden on the FileRead node, so the Remote Transfer, Transfer protocol, and Server identity properties must be configured as required.

When the FileIterator node propagates to the End of Files terminal, the LocalEnvironment contains a FileIteratorResults section. The FileIteratorResults section summarizes how the list of files was processed. The high-level structure of the FileIteratorResults section is:

LocalEnvironment
  - FileIteratorResults
    - Summary
    - Files
      - File

The Summary section has the following elements:

Element Name	Element Data Type	Description
Successful	BOOLEAN	The overall result of the FileIterator node. If all the files in the list are processed successfully, then the value is TRUE. Otherwise, it is FALSE.
TotalEntries	INTEGER	The total number of files in the list.
ValidEntries	INTEGER	The total number of valid entries in the file list.
SuccessfulEntries	INTEGER	The number of files that were iterated successfully.
FailedEntries	INTEGER	The number of files that were iterated that caused an exception or error.

The Files section has a File entry for each File that was in the input file list. The Files section has the following elements:

Element Name	Element Data Type	Description
Directory	CHARACTER	Absolute directory path of the input directory in the form used by the file system of the integration server. For example, on Windows systems, the directory path starts with the drive letter prefix (such as C:) This field is only included when the FileEntry was for a local file.
ServerDirectory	CHARACTER	The directory on the FTP Server where the file was located. This field is only included when "Remote Transfer" was used on the FileExists node.
Name	CHARACTER	File name and extension.
Propagated	BOOLEAN	Indicates whether this entry was propagated to the "out" terminal or not.
Successful	BOOLEAN	Indicates whether this entry was processed successful or not.
Exception	Exception	(Optional) If the entry was not successful such that an exception was thrown then the ExceptionList for this entry are included in th Exception section.

When the LocalEnvironment is propagated to the "End of Files" terminal the content from the LocalEnvironment that was received by the FileIterator node is included.

Using this node in a message flow

The FileIterator node can be used in any message flow that accepts messages in files. You can use it to accept input from a FileExists node and send output to a FileRead node.

Terminals and properties

The FileIterator node terminals are described in the following table:

Terminal	Description
Failure	The output terminal to which a message is routed if an error occurs before a message is propagated to the Out terminal. If the "End of Files" terminal is connected, then any errors are reported as part of the `FileIteratorResults` section instead of being propagated to the Failure terminal.
Out	For each File entry in the LocalEnvironment (as created by the FileExists node), the Out terminal is propagated to. For multiple files entries, the out terminal is propagated to multiple times. For a File entry to be propagated to the out terminal, the entry must have a valid Directory and Name element.
End of files	When all of the File entries are processed, the "End of Files" terminal is propagated to. The message propagated to this terminal contains the original `LocalEnvironment` received by the FileIterator node and a newly added `FileIteratorResults` section that reports whether the propagations were successful or not.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory. The column headed C indicates whether the property is configurable (You can change the value when you add the message flow to the BAR file to deploy it).

The Description properties of the node are described in the following table. You can enter a Short description, a Long description, or both. You can also rename the node on this tab.

Property	M	C	Default	Description
Node name	No	No	FileExists	The name of the node.
Short description	No	No	None	A brief description of the node.
Long description	No	No	None	Text that describes the purpose of the node in the message flow.

The Monitoring properties of the node are described in the following table.

Property	M	C	Default	Description
Events	No	No	None	Events that you define for the node are displayed on this tab. By default, no monitoring events are defined on any node in a message flow. Use Add, Edit, and Delete to create, change, or delete monitoring events for the node; see Configuring monitoring event sources by using monitoring properties for details. You can enable and disable events that are shown here by selecting or clearing the Enabled check box.