FileExists node

Use the FileExists node to poll for the existence of a specified file at a specified location, and to delete or leave the file in the file directory without processing the file contents.

This topic contains the following sections:

Purpose

You can use the FileExists node to process a file from a directory without needing to read the file contents. The metadata for the file is propagated down the flow without processing the contents of the file. The file contents can then be read and processed by another node (such as a FileRead node) later in the flow. You can also choose whether to delete the file or leave it in the file directory after it is propagated through the flow.

The FileExists 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 FileExists node does not read the contents of the file, so the message tree does not contain a message body. When the FileExists node propagates message trees, it stores information about the files that it has detected in the local environment. If the List Mode property in the FileExists node is not set, the file information is stored in the LocalEnvironment.File message tree. If the List Mode property on the node is set, multiple file records are stored in the LocalEnvironment.Files message tree. For each file record, in either LocalEnvironment.File or LocalEnvironment.Files.File[n], the following table lists the LocalEnvironment.File message tree structure. The elements contain data about the current record.

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 path starts with the drive letter prefix (such as C:).
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 input node started to process the file as a character string.
TotalInList INTEGER The total number of files in the list of files.
FromFTP BOOLEAN True if one or more files were detected on an FTP server.
ServerDirectory CHARACTER When you use "Remote Transfer", the element ServerDirectory is the value of the server directory that is specified on the FileExists node. When you do not use "Remote Transfer", the element ServerDirectory is not included in the LocalEnvironment.
Server CHARACTER When you use "Remote Transfer", the values of "server and port" are as specified on the FileExists node. When you do not use "Remote Transfer", this element is not included in the LocalEnvironment.
The following elements contain data about the current file:
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 node that processed the file.

Using the FileExists node in a message flow

The FileExists node can be used in any message flow that accepts messages in files.

When you put an instance of the FileExists node into a message flow, you can configure it. For more information, see Configuring the FileExists node. The properties of the node are displayed in the Properties view. All mandatory properties with no defined default value are marked with an asterisk. You must enter a value for these properties.

If you configure a File node to use FTP, your network might need it to connect to an FTP proxy server, instead of directly to the remote FTP server. How you configure the File nodes to use an FTP proxy depends on how that proxy handles requests. For some FTP proxies, you must encode the target FTP server information in the logon credentials that you create with the mqsisetdbparms command. For example, some FTP proxies support the following values: 
Username: FtpTargetHostUsername@ProxyUserName@TargetFtpHostname 
Password: TargetFtpUserPassword@ProxyUserPassword
Other proxies might require a different encoding, or might require external configuration, or you might not be able to use them with the File nodes.

You can use a FileExists node with a FileIterator node to detect a set of files in a specified directory. For more information, watch the following video: Using a FileExists node with a FileIterator node.

Terminals and properties

The FileExists 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.
Out The output terminal to which a message is routed if it was successfully extracted from the input file. If no errors occur within the input node, a message that was received from an external resource is always sent to the Out terminal first.
Catch The output terminal to which the message is routed if an exception is thrown downstream and caught by this node. Exceptions are caught only if this terminal is attached.

The following tables describe the node properties. The column headed M indicates whether the property is mandatory (marked with an asterisk if you must enter a value when no default is defined). 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:

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 Basic properties of the node are described in the following table:

Property M C Default Description mqsiapplybaroverride command property
Input directory Yes Yes None When not using the "Remote transfer" option, this value is the path of the directory from which input files are detected. The directory must be in a file system to which the integration server has access. If the input directory does not exist, no files are detected. The FileExists node checks that the input directory exists at intervals that are defined by the polling interval property. When you use the "Remote transfer" option, the input directory does not need to be specified as the input files are detected from the Server Directory. However, the input directory can be specified and this directory is included in LocalEnvironment that is propagated from the FileExists node. A FileIterator node propagates the input directory value so that is can be used by a FileRead node as a local staging directory for transferring files.

Specify the directory as either an absolute or a relative directory path. If the directory path is relative, it is based on the directory that is specified in the environment variable MQSI_FILENODES_ROOT_DIRECTORY. An example on Windows systems is C:\fileinput. An example on UNIX systems is /var/fileinput. On Windows, if you are specifying a shared directory that is mapped to your local computer, specify the share name instead of the letter that represents the drive; for example \\myshare\mydirectory.

 inputDirectory
Include local subdirectories Yes Yes False Determines whether all subdirectories under the specified input directory must also be searched for files to process. When you use "Remote transfer", this option is ignored. recursiveDirectories
List mode No No False By default the FileExists node processes one file at a time. The input or server directory is scanned for the next file and then the information about that one file is propagated to the message flow in the LocalEnvironment. When List Mode is set, all the files in the input or server directory are detected, and the list of files is propagated in the LocalEnvironment.  
File name or pattern Yes Yes * A file name or string that contains optional wildcard characters (* and ?) or a regular expression that identifies the file or files to process from the input or server directory. If you specify a regular expression, you must enclose it in parentheses. filenamePattern
File exclusion pattern No Yes None A simple string that contains wildcard characters (* and ?) or a regular expression that identifies files to exclude from processing. If you specify a regular expression, you must enclose it in parentheses. excludePattern
Delete files No No Always Determines whether the input file is deleted after it is propagated through the node. Possible values are Always and Never. Default is Always.
  • If this property is set to Always, the file is deleted when it has been processed by the flow. The current transaction commits regardless of whether the file is deleted successfully. If you require any issues with the file deletion to be included in the transaction, they must be handled elsewhere in the flow (with a FileRead node, for example).
  • If this property is set to Never, the FileExists node never deletes the file and the flow logic is responsible for deleting the file on the Out, Catch, or Failure terminal.

When this property is set to Always, the file directory must be opened with write/execute permissions. When it is set to Never, the file directory can be opened with read-only permissions.

  

The Polling properties of the node are described in the following table:

Property M C Default Description mqsiapplybaroverride command property
Polling interval (seconds) Yes Yes 5 The polling interval in seconds. waitInterval

The Retry properties of the node are described in the following table:

Property M C Default Description mqsiapplybaroverride command property
Retry mechanism Yes No Failure How the node handles a flow failure. Valid options are:
  • Failure
  • Short retry
  • Short and long retry
  
Retry threshold Yes Yes 0 The number of times to try the flow transaction again when the Retry mechanism property value is Short retry. retryThreshold
Short retry interval (seconds No Yes 0 The interval, in seconds, between each retry if Retry threshold property is not zero. shortRetryInterval
Long retry interval (seconds) No Yes 300 The interval between retries, if the Retry mechanism property is Short and long retry and the retry threshold has been exhausted. longRetryInterval

FTP properties:

Property M C Default Description mqsiapplybaroverride command property
Remote Transfer No Yes Cleared This property defines whether the node uses the remote file transfer properties that are listed on the FTP tab and reads files from either an FTP or SFTP server. If you select this property and the Include local subdirectories property, only the top-level directory that you have specified on the remote system is searched for files. fileFtp
Transfer protocol No Yes FTP This property specifies the protocol to be used for remote transfer. Valid values are:
  • FTP
  • SFTP
 remoteTransferType
Remote server and port No Yes None This property can have either of the following values:
  • The IP address or name (and optionally, the port number) of a remote FTP or SFTP server. For example: ftp.server.com:21 or sftp.server.com:22
  • The name of an FTP Server policy in the format {policyProjectName}:PolicyName (see FTP Server policy (FtpServer))
If a policy name is specified, any of the other remote transfer properties on the FTP tab can be overridden by the policy. 		fileFtpServer
Security identity No Yes   The name of the user identification that is used to access the FTP or SFTP server. This property is overridden by the FTP security identity property, if set in the FTP Server policy. fileFtpUser
Server directory No Yes "." The directory on the FTP or SFTP server from which to transfer files. If you specify this property as a relative path, it is relative to the home directory after logon. This property is overridden by the Remote FTP server directory property, if set in the FTP Server policy. If the directory that is specified in this field does not exist on the remote server, the node attempts to create it. fileFtpDirectory
Scan delay No Yes 60 The delay, in seconds, between remote directory scans. This property overrides the value set for Polling interval when the Remote Transfer property is selected. This property is overridden by the Scan delay property, if set in the FTP Server policy.  

The Transactions properties of the node are described in the following table:

Property M C Default Description
Transaction mode No Yes No The transaction mode on this node determines whether the rest of the nodes in the flow are run under sync point. Valid options are:
  • Yes
  • No
The Instances properties of the node are described in the following table:
Property M C Default Description mqsiapplybaroverride command property
Additional instances pool No Yes Use Pool Associated with Message Flow The pool from which additional instances are obtained.
  • If you select Use Pool Associated with Message Flow, additional instances are obtained from the message flow pool.
  • If you select Use Pool Associated with Node, additional instances are allocated from the additional instances of the node based on the number that is specified in the Additional instances property.
 componentLevel
Additional instances No Yes 0 The number of additional instances that the node can start if the Additional instances pool property is set to Use Pool Associated with Node. additionalInstances

When a FileExists node is used in a message flow with additional instances, it is likely multiple message flow threads will see the same lists of files. Therefore, any message flow nodes that are used in the message flow must be implemented such that other threads might have already processed/deleted a file in the list.

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

The FileExists node does not read the contents of the file and so monitoring events cannot include any Event Payload data even if it is configured on the monitoring event definition