DC 12.3 | FTP Queue

User Guide > Process Steps and Components > Queue Step > FTP Queue

Was this helpful?

FTP Queue

Note: For general information about Queue Steps, see Queue Step.

The FTP Queue enables you to send and receive files using a secure or non-secure FTP connection. It allows a folder on an FTP site to be considered like a message queue. The files in the folder can be retrieved into message objects by using the GetMessage action in a Queue step.

Message objects can also be written to the folder as files using the PutMessage action. The properties control the files that are read and the names of the files that are written.

The primary functions of FTP Queue are:

• Connect to and disconnect from a secure or unsecure FTP server

• Retrieve a file from an FTP server and insert it in a message object

• Put a message object into the selected file on an FTP server

This component has the following versions:

• FTP Queue 1.0.0 - Provides an non-secure connection. While version 4.1.0 is recommended, 1.0.0 is supported for backward compatibility with existing processes.

• FTP Queue 4.1.0 - Provides either a secure or non-secure connection using one of the three FTP types:

– FTP (non-secure)

– SFTP (secure FTP over SSH)

– FTPS (secure FTP over SSL (certificate-based authentication))

Active and Passive Modes

FTP Queue 1.0.0 tries passive mode first. If it fails to connect, then it tries active mode.

FTP Queue 4.1.0 uses active mode for processing.

Encoding

In secure connections, FTP Queue 4.1.0 uses ISO-8859-1 to encode binary data.

FTP Queue 1.0.0 Properties

Property	Default Value	Description
User Name		Username to connect to the server.
Password		The password to authenticate the above username.
FTPSite		Name of the server to connect to. To use FTPSite: • Configure FTPS server. The server must use a valid server certificate (Company-signed or CA-signed certificate). Do not use the self-signed certificate. • When you use Active mode, there is no firewall between the client computer and the FTPS server. Type the FTP server name or IP address, port number, and directory in the following format: FTP_server:port/directory_name The port number and directory name are optional. If you specify the port number, the component uses the default port number for the selected FTP server type.
Serialize	FALSE	When a message object is written to a file with the PutMessage action, only the message body is written. The Serialize property indicates whether to write the message properties to a separate file with an .hdr extension.
Deserialize	FALSE	If a message object was written to a folder with the Serialize property set, the message properties are stored in a separate file with an .hdr extension. When reading a file from a folder using the GetMessage action, the Deserialize property indicates that the message properties must be read from the .hdr file.
RetryCount	0	Number of times to retry if there is a failure to connect to the FTP site.
FilenameFormat	MessageFile%n	When writing a message object to a file using the PutMessage action, this format is used to create the file name. The following format specifications can be used to build the format. Each specification begins with a percent sign (%). The specifiers represent properties on the message object that are created by the File Folder Iterator. Any or all of the specifications can be included in any order. Note: The format must generate unique names for the files. The supported formats are: • MessageFile%n • %i TransferId • %p PieceNumber • %s SourceName • %h TargetHostName • %t TargetName • %d Transport Start Date/Time • %n Number starting with 0 (zero) • %c Current date/time stamp displaying number of seconds elapsed since midnight GMT January 1, 1970 (value always contains 10 digits) Examples TargetName: TargetFFQFile PieceNumber: 5 FileFormat: %t%p MessageClass: dat Filename: TargetFFQFile5.dat
		Best Practice — The %n and %c format specifications enable you to create unique file names for generic messages. These should be used together to ensure greatest efficiency. If only %n is used in the file name specification, for example, MessageFile%n, the connector tries to assign the file name "MessageFile0" when a message is created. If this is unique it is used, but if it already exists in the specified directory, %n is incremented by 1 and this is checked against existing files. This continues until a unique file name is found. This means that the more messages that are created, the longer it takes for a unique name to be found. If only %c is used, the process is limited to writing one file per second as the file name it tries to assign for the new message is not unique until the timestamp has advanced. Therefore, use a combination of %n and %c. For example, MessageFile%c%n creates as many messages each second as required and %n is reset to 0 each time the timestamp changes.
GetMsgClass	dat	The file extension that is appended to the file name when reading a file with the GetMessage Action.
PutMsgClass	dat	File extension that is appended to the file name generated by the FileFormat property when writing a message object to a file with the PutMessage action.
Working Directory		Directory name used to store temporary files that are created when retrieving files with the GetMessage action.
Pattern	*	Pattern used to detect files to be read, such as File* or *95. To retrieve a specific file, type the exact file name without the extension. The extension is read from the File Extension option.
MessageTimeOut	5	Indicates the number of times to query the FTP folder to get the desired message. Default is 5. This option works with the SleepInterval option.
PollingTimeOut	5	Indicates the maximum total time to take to retrieve all files from the folder. Use this option with the Polling TimeOut Type option.
PollingTimeOutType	Minutes	Type of the PollingTimeOut value. The available options are: • Years • Months • Days • Hours • Minutes • Seconds
SleepInterval	1000	Time interval, in milliseconds, to wait between queries if there are no messages in the queue to process. This option works with the Message TimeOut option.
BrowseMode	FALSE	Indicates whether the file on the FTP server from which the message is read is deleted. If Browse Mode is TRUE, the file is not deleted.
SourceEncoding	0	Character set of the source data. This indicates using the default character set for the system. The ENC_ names can be used in expressions for setting the encoding value. On the integration engine command line, the number must be used.
Binary Indicator	FALSE	Indicates whether the files being read should be opened in binary mode.

Supported Actions for FTP Queue 1.0.0

Action	Description
Connect	Establishes a connection to an FTP server, which is useful when you are testing your configuration.
Disconnect	Breaks the connection with an FTP server, which is useful when you need to disconnect before a process is complete.
GetMessage	Connects to an FTP server, retrieves the contents of a file into a message object, then disconnects. The GetMessage action sets the SourceName message property to the name of the file from which it retrieved the message.
PutMessage	Connects to an FTP server, writes a message object to the specified file, then disconnects.

Supported Action Parameters for FTP Queue 1.0.0

Action	Parameter	Description
GetMessage, PutMessage	Message	Name of the message.

FTP Queue 4.1.0 Properties

Property	Default Value	Description
User Name		Username to connect to the server.
Password		The password to authenticate the above username.
Server Name	localhost	Name of the FTP server to connect to. Type the FTP server name or IP address, port number, and directory in the following format: FTP_server:port/directory_name The port number and directory name are optional. If you do not specify the port number, the component uses the default port number for the selected FTP server type. Note: Support has been provided for Unicode characters. Unicode is a standard encoding system that is used to represent characters from almost all languages.
FTP Type	FTP	Choose from the following FTP TypesChoose from the : • FTP • SFTP Note: FTP Queue 4.1.0 does not support the ssh-rsa encryption algorithm for SFTP server. • FTPS
FTP Encryption	EXPLICIT	Choose from the following FTP Encryption types: • EXPLICIT - Explicit FTPS is the newer method of FTPS transfer and is supported by majority of FTP servers. In Explicit FTPS the client "explicitly" requests the server to create a secured session, using SSL/TLS. • IMPLICIT - Implicit FTPS was the first method created to encrypt data sent via FTP and in this connection the SSL encryption is “implied”. As soon as a connection is established between the FTPS client and the file transfer server, both command and data channels are automatically protected with SSL encryption. Thus the entire FTP session is encrypted, in contrast to flexibility you have when using explicit FTPS. However, implicit FTPS is considered a deprecated protocol, meaning that it not the current standard. This property is only applicable for FTPS and is displayed when FTP Type is selected as FTPS.
FTP Connection Mode	Active	Choose from the following FTP Connection Mode types: • Active • Passive Note: This is not applicable for SFTP.
Message Payload Type	File Contents	Choose from the following Message Payload Type: • File Contents: If the actions are: – If GetMessage is the, contents of the retrieved file are stored in the DJMessage. – If PutMessage, contents of the DJMessage are sent to the remote FTP site and stored as a file. • File Location: If actions are: – GetMessage - File retrieved from the remote FTP site is stored directly as a file. – PutMessage - Local file contents are sent to the remote FTP location.
Encoding Type	ISO8859-1	Select ISO8859-1 or UTF-8. Note: This is not applicable for SFTP.
Binary Indicator	FALSE	Indicates whether the files being read must be opened in binary mode.
Truststore		Path to trust store file. The component compares the server certificate against the certificates in the specified truststore file. If the server certificate is not already in the truststore file, it results in an error. The file type of the truststore is Java key store (JKS). This property is only applicable for FTPS and is displayed when FTP Type is selected as FTPS.
Truststore Password		Password associated with the Truststore. This property is only applicable for FTPS and is displayed when FTP Type is selected as FTPS.

Supported Actions for FTP Queue 4.1.0

Action	Description
Connect	Establishes a connection to an FTP server, which is useful when you are testing your configuration.
Disconnect	Breaks the connection with an FTP server, which is useful when you need to disconnect before a process is complete.
GetMessage	Connects to an FTP server, retrieves the contents of a file into a message object, then disconnects. The GetMessage action sets the SourceName message property to the name of the file from which it retrieved the message.
PutMessage	Connects to an FTP server, writes a message object to the specified file, then disconnects.

Supported Action Parameters for FTP Queue 4.1.0

Action	Parameter	Description
GetMessage, PutMessage	Message	Name of the message.

Supported Action Properties for FTP Queue 4.1.0

Action	Property	Default Value	Description
GetMessage	Target Directory		Target directory for storing the retrieved file on the local machine.
	Pattern	*	Pattern used to detect files to be read. To retrieve a specific file, type the exact file name with or without the extension. The extension is read from the File Extension option. The pattern is case sensitive. The Pattern properties supports the use of regular expressions. Default is . For example, File, 95, File?, ?95('' matches any character sequence and '?' matches any character).
	File Extension		File extension to append to the file name when retrieving a file and inserting into a message object. Use values such as txt and asc. Do not enter the dot (.), the extension string.
	Mget Mode	FALSE	When TRUE, all the files are retrieved in a single call and copied into the specified target directory, and the supplied DJMessage Body is populated with the comma separated list of retrieved file names. The number of files retrieved is stored in the FileCount property of DJMessage. The Mget Mode option is only visible when the Message Payload Type property is set to File Location. This option is hidden when the Message Payload Type property is set to File Contents.
	Browse Mode	FALSE	Indicates whether the file on the FTP server from which the message is read is deleted. If Browse Mode is TRUE, the file is not deleted.
	Message TimeOut	5	Indicates the number of times to query the FTP folder to get the desired message. Default is 5. This option works with the SleepInterval option.
	Sleep Interval	1000	Time interval, in milliseconds, to wait between queries if there are no messages in the queue to process. This option works with the Message TimeOut option.
	Polling TimeOut	5	Indicates the maximum total time to take to retrieve all files from the folder. Use this option with the Polling TimeOut Type option.
	Polling TimeOut Type	Minutes	Type of the PollingTimeOut value. The available options are: • Years • Months • Days • Hours • Minutes • Seconds
PutMessage	Remote Directory		Remote location for storing the file on the FTP Server.
	Filename Format		Format for the file name written to the message object. Various format specifications are supported. Each specification begins with a %. Any or all specifications can be placed consecutive to each other. However, you may not place text after a format specification. For example, MessageFile%n%s is valid, but MessageFile%nTest is invalid. Make sure that the format generates a unique name for each file. The default format is MessageFile%n, which produces the file name MessageFile0. The supported format specifications are: • %n - Inserts a number, starting with 0 (zero). • %c - Inserts current date/time stamp, displaying number of seconds elapsed since midnight GMT January 1, 1970. The value has 10 digits. • %s - Inserts the source file name, which can be specified as a message property. • %t - Inserts the target file name, which can be specified as a message property.
	File Extension		File extension to append to the file name when writing a message object to a file. Use values such as txt and asc. Do not enter the period, only the extension string.
	Use Temporary Files
	Local File		Local path to the location where the file exists.

Errors

The following table provides possible FTP Queue error codes.

Error Code	Description
4	Error occurs while trying to get a message from the FTP server.
8	Error occurs while trying to add a message on the FTP server.
12	Error occurs because the GetMessage or PutMessage actions cannot find the specified file.
19	Error occurs while trying to connect to the FTP server.
27	Error occurs while trying to disconnect from the FTP server.

The process log may also contain messages related to FTP Queue.

Error Code	Description
28047	An error occurred executing a queue step. This run-time error can result from a change in the server certificate after you deploy your integration application. View the process log for the following message: "Error connecting to FTP Server: Could not validate server certificate. Please make sure you run TestConnect and save the process." To resolve this error, do one of the following. • Obtain a new certificate and add it manually to the client trust store file. • In the process file, use the Test Connect option to connect to the FTP server so that it prompts you to accept the new certificate.

Error Code

Description

28047

An error occurred executing a queue step.

This run-time error can result from a change in the server certificate after you deploy your integration application. View the process log for the following message:
"Error connecting to FTP Server: Could not validate server certificate. Please make sure you run TestConnect and save the process."

To resolve this error, do one of the following.

• Obtain a new certificate and add it manually to the client trust store file.

• In the process file, use the Test Connect option to connect to the FTP server so that it prompts you to accept the new certificate.

Limitations

• The file transfer is bound by the amount of physical memory and heap size.

• If you are transferring binary files, you must encode the data in the message object in Base64. When you receive files with GetMessage in binary mode, the files will be binary, and will not be encoded in Base64.

Last modified date: 12/03/2024