The following table lists the configuration properties that can be set dynamically using message properties on the outgoing or incoming message.
Configuration parameters marked as a connection property cause the connection to the FTP / FTPS / SFTP server to be re-established if they change in any way. Changes to other configuration properties do not require re-establishing the connection (however, the connection is re-established if it is not currently up).
The (S)FTP Client Communication Point can also be configured dynamically using XML Configuration Templates. Refer to Dynamic Configuration Using XML Templates for details on the differences between the two configuration modes.
|
Configuration Property
|
Message Property
|
Message Property Values
|
Example
|
Connection Property
|
|---|---|---|---|---|
| Protocol | ConnectionType |
Sets the type of connection protocol to use:
The outgoing message will be sent to the error queue if the property is set to an empty string or invalid value. The selected FTP protocol determines which other configuration properties are queried when merging the configuration. For example, the SSL server certificates are completely ignored when not using FTPS. |
FTPSExplicit |
Yes |
| Server | ServerHostname |
Sets the hostname or IP address of the server. If the property is set to an empty string, then the statically configured value is used instead. If neither this property nor the static configuration set this parameter, the outgoing message will be sent to the error queue. |
ftp.example.com |
Yes |
| Port | ServerPort |
Sets the port number that the server is listening on. This can be set to |
22 |
Yes |
| Read Timeout | ReadTimeout |
Sets the socket read timeout used when expecting a response from the FTP server If it is set to an empty string then the statically configured read timeout will be used. If it is set to a non-integer or a value less than 1000ms the outgoing message will be sent to the error queue. |
60000 |
Yes |
| Connection Mode | ConnectionMode |
Sets the connection mode to use for data channels when connecting to an FTP or FTPS server:
If set to an empty string or an invalid value then it is ignored and the statically configured value is used instead. This parameter is completely ignored when using the SFTP protocol. |
passive |
Yes |
| Transfer Mode | TransferMode |
Sets the data transfer mode to use when uploading and downloading files:
If set to an empty string or an invalid value then it is ignored and the statically configured value is used instead. |
ascii |
No |
| Server Validation Mode | ServerValidationMode |
Determines how the SSL certificates or SSH public keys are found for an FTPS or SFTP connection. See the Server Validation Mode property description for details about each option.
If set to an empty string or an invalid value then it is ignored and the statically configured value is used instead. |
allowDynamicKeyLookup |
Yes |
SslServerCertificates |
The SSL server certificates to use to validate the FTPS server prior to authenticating the client. This property is configured by setting it to a property list with each value in the list containing the alias of an SSL certificate that may be used to validate the FTPS server. Each of these aliases must correspond to an SSL certificate that has previously been loaded into the Certificate and Key Manager in the Rhapsody IDE. A connection cannot be established to an FTPS server unless it presents a certificate chain that can be validated using the certificates configured in the communication point. If FTPS is being used then it is mandatory to provide at least one SSL certificate to validate the server unless the Server Validation Mode does not require this, however, this may be provided either statically at configuration time, or dynamically using this message property. If at least one SSL certificate is provided using the message property, then the certificates from the message property override any that may have been configured statically. If no certificates are provided when FTPS is in use, the outgoing message is sent to the error queue. Empty certificate aliases in the list are ignored, however, the outgoing message is sent to the error queue if it references a certificate that could not be found. The SSL certificates are completely ignored if FTPS is not being used. |
|
Yes | |
| Hostname Validation | SslHostnameValidation |
This property determines if hostname validation is performed on the SSL certificate presented by the FTPS server:
If SSL hostname validation is enabled, the connection can only be established if the certificate presented by the FTPS server contains the hostname that we used to connect to the FTPS server in either the Subject's Common Name (CN),oras a DNS name in the SubjectAlternativeName extension. Hostname validation is never performed if the configured server hostname is either If set to an empty string or invalid value then it is ignored and the statically configured value is used instead. |
disabled |
Yes |
| Cipher Suites | CipherSuites |
The level of SSL cipher suites or SSH algorithms that should be enabled for this connection:
If it is set to an empty string or invalid value then it is ignored and the statically configured value is used instead. |
FIPS |
Yes |
| SSL Client Private Key | SslClientPrivateKey |
The SSL private key to use for SSL client authentication when connecting to an FTPS server. This property is set to the alias of an SSL private key which has previously been added to the Certificate and Key Manager in the Rhapsody IDE. If requested by the FTPS server, the certificate associated with this private key is presented to the server as part of the SSL handshake. An error is thrown if the configured alias does not correspond to an SSL private key in Rhapsody's key store. If set to an empty string then the statically configured value is used instead. This property is completely ignored if FTPS is not being used. |
sslPrvKey |
Yes |
| SFTP Server Public Key | SshServerPublicKeys |
The SSH public keys to use to validate the SFTP server prior to authenticating the client. This property is configured by setting it to a property list with each value in the list containing the alias of an SSH public key that may be used to validate the SFTP server. Each of these aliases must correspond to an SSH public key that has previously been loaded into the Certificate and Key Manager in Rhapsody IDE. A connection cannot be established to an SFTP server unless its public key has been configured on the communication point. If SFTP is being used then it is mandatory to provide at least one SSH public key to validate server unless the Server Validation Mode does not require this, however, this may be provided either statically at configuration time, or dynamically using this message property. If at least one SSH public key is provided using the message property, then the public keys from the message property override any that may have been configured statically. If no public keys are provided when SFTP is in use, the outgoing message is sent to the error queue. Empty SSH public keys in the list are ignored, however, the outgoing message is sent to the error queue if it references a public key that could not be found. The SSH public keys are completely ignored if SFTP is not being used. |
|
Yes |
| SFTP Client Authentication Mode | SshClientAuthMode |
Sets the type of SSH client authentication that will be performed:
If set to an empty or invalid value the statically configured value is used instead. |
publickey |
Yes |
| SFTP Client Private Key | SshClientPrivateKey |
The SSH private key to use for client authentication when one of the public key authentication modes has been enabled. This property is set to the alias of an SSH private key that has previously been added to the Certificate and Key Manager in Rhapsody IDE. An error is thrown if the configured alias does not correspond to an SSH private key in Rhapsody's key store. If set to an empty string then the statically configured value is used instead. If SSH public key authentication has been enabled it is mandatory to provide an SSH private key, either in the static configuration or by using this message property. The outgoing message will be sent to the error queue if this is not done. This property is completely ignored if SFTP is not being used. |
sshPrvKey |
Yes |
| SFTP Compression | SshCompressionModes |
This property is configured by setting it to a property list with each value in the list containing one of the following values:
If no compression modes are specified then the statically configured compression modes are used instead. If no static compression modes were configured then all of the compression algorithms are automatically enabled. Empty values in the property list are ignored, but invalid values will cause the outgoing message to be sent to the error queue. Bear in mind that the SFTP server is free to select any of the advertised compression algorithms to use during SSH negotiation. Consequently, if all three algorithms are enabled the SFTP server is free to select the no compression algorithm rather than one of the algorithms that compress the data. |
|
Yes |
| SFTP Advanced Configuration Flags | SshConfigFlags |
It is configured by setting it to a property list with each value in the list containing one of the following values:
Setting this property to an empty string or empty list disables all of these configuration flags. Empty values in the property list are ignored, but invalid values cause the outgoing message to be sent to the error queue. |
|
Yes |
| Server Line Endings | SshRemoteEol |
Used when performing ASCII mode file transfers to SFTP servers, as SFTP does not natively support ASCII mode transfers. The server line endings are then compared to the local line endings in order to determine if any transformation is required. The property can be set to one of the following values:
If it is set to an empty string or invalid value, then the statically configured value is used instead. In Auto Detect mode, the (S)FTP Client communication point will attempt to infer the line endings used by the SFTP server by examining the server information heading returned when the connection is established. This will only work if that server information contains a newline, and uses the correct newline characters for the platform that it is running on. As not all SFTP servers do this correctly, this option is available to override the default behavior when required. |
unix |
Yes |
| Username | Username |
If this message property is set to an empty string, then the username is treated as an empty string rather than reverting to the statically configured value. Note that the meaning of an empty username is defined by the FTP server: some servers may regard it as an anonymous login, but others may just reject the authentication attempt. | jdoe |
Yes |
| Password | Password |
If this message property is set to an empty string, then the password is treated as an empty string rather than reverting to the statically configured value. The password is ignored when using SFTP with public key authentication. As message properties are visible in the Management Console to users with the appropriate access rights, it is highly recommended that you encrypt passwords provided in this message using the Encrypt Password function in the Rhapsody IDE. Alternatively, you can use Configuration Templates, which do not require providing the password in a message property. If the passwords are retrieved from a Rhapsody variable using JavaScript, then the retrieval functions can leave them in this format. Refer to Encrypted Rhapsody Variables for details. |
secret |
Yes |
| Character Encoding | CharacterEncoding |
Sets the character encoding to use for the control channel. This affects how the names of files and directories are interpreted by the remote server. This should be set to a valid Java character encoding name, and is case-insensitive. If this message property is set to an empty string then the statically configured character encoding will be used. | UTF8 |
Yes |
| Connection Establishment Mode | ConnectionEstablishmentMode |
Specifies whether to maintain a constant connection to the FTP server or to disconnect the connection immediately after it becomes idle:
|
[maintainConnection] |
Yes |
|
Sets the IP address that the communication point will listen on for active mode FTP / FTPS connections. The message property can be given an empty value if you want to clear the static configuration and just use the sensible defaults. If a value is specified for the property, it will be validated to make sure it is a valid IPv4 address, and if it fails validation the message will be sent to the error queue. |
|
Yes |
|
|
Sets the range of allowed ports that the communication point will listen on for active mode FTP / FTPS connections. The message property can be given an empty value if you want to clear the static configuration and just use the sensible defaults. If a value is specified for the property, it is validated to make sure it is a valid port range in the format we are expecting (that is, two valid port numbers separated by a dash) and if it fails validation the message will be sent to the error queue. |
|
Yes |
|
|
Sets optional settings that may be required for compatibility with certain servers:
Setting this property to an empty string or empty list disables all of these configuration flags; any that are not included in the list are also disabled. Empty values in the property list are ignored, but invalid values cause the outgoing message to be sent to the error queue. |
|
Yes |
|
|
Provides options to work around some known bugs in various FTPS servers:
Setting this property to an empty string or empty list will disable all of these configuration flags; any that are not included in the list are also disabled. Empty values in the property list are ignored, but invalid values cause the outgoing message to be sent to the error queue. |
|
Yes |
|
|
The proxy server type:
|
|
Yes |
|
|
Sets the hostname or IP address of the proxy server. |
|
Yes |
|
|
Sets the port to connect to the proxy server on. This must be a valid port number (in other words, between 1 and 65535), otherwise the message will be sent to the Error Queue. |
|
Yes |
|
|
Sets the public address of the proxy server. |
|
Yes |
|
|
Sets the username to authenticate to the proxy server with. |
|
Yes |
|
|
Sets the password to authenticate to the proxy server with. This is not required for the SOCKS4 protocol as it does not support password authentication. |
|
Yes |
|
| Generate Message When No Response | GenerateResponseMessage |
The generate message when no response mode:
If an invalid value is detected, it uses the static value. |
enabled |
No |
| Input Directory | InputDirectory |
Sets the base input directory to use when downloading files. No validation is done on this, in other words it can be empty, in which case the input would be received from the |
dir1/dir2 |
No |
InputPatternType |
The type of the input pattern used to match files for download:
If an invalid value is detected, it uses the static value. |
wildcard |
No | |
| Input Pattern | InputPattern |
The pattern used to filter input files. Validation will be done on this value. If the value is left empty, the message is sent to the error queue. If the Input Pattern Type is set to |
*.txt |
No |
| Input Directory Navigation Mode | InputDirectoryNavigationMode | Specifies whether to use FTP commands to access the target directory directly, or navigate to the target directory via the home directory:
|
changeDirectly |
No |
DirectoryTraversalMode |
Determines whether the communication point will just download files from the configured input directory or will instead traverse child directories in order to find matching file:
If an invalid value is detected, it uses the static value. |
inputDirOnly |
No | |
| Follow Symbolic Links | SymbolicLinkAction |
Determines how the communication point handles symbolic links when downloading files from the FTP server. If the communication point is configured in Out->In mode, the message property
If |
ignore |
No |
PostDownload Action |
Determines what the communication point does with the remote files after they have been downloaded:
If an invalid value is detected, it uses the static value. |
delete |
No | |
| Rename To | RenameTo |
Sets the target filename for a rename after downloading a file. This is ignored if not renaming files after downloading them, but otherwise is required to be configured either in the static configuration or the configuration template. This may contain a number of variables described in the Rename To configuration property to reference the old filename or current date/time. If renaming files after downloading them is enabled, this must be set either as a message property or in the static configuration. It must not be set to exactly |
%filename%.done |
No |
InputLocales |
Sets the input locales used for a particular message can be changed dynamically by setting the message property InputLocales to a property list containing the list of Java locales that should be used. |
|
Yes | |
DirectoryListingParser |
Specifies directory listing parser used for a particular message can be changed dynamically by setting the message property
|
unix |
Yes | |
JavaScriptDirectoryParser |
The JavaScript directory parser can be changed dynamically by setting the message property |
if (line.length > 49){
contents.add({
name: line.substring(49),
isDirectory: line[0] == 'd'
});
}
|
Yes | |
| Before Receive Commands | BeforeReceive |
A property list is used to configure the custom commands. Each entry in the property list is comprised of two parts separated by a pipe character: the error action, and the command. The following error actions are supported:
You must provide both an error action and a non-empty command. |
|
No |
| After Receive Commands | AfterReceiveCommands |
A property list is used to configure the custom commands. Each entry in the property list is comprised of two parts separated by a pipe character: the error action, and the command. The following error actions are supported:
You must provide both an error action and a non-empty command. |
|
No |
ArchivingStrategy |
Indicates whether messages arriving on this communication point are to be archived as per standard archiving strategies:
|
normal |
No | |
| Maximum File Size for Download | MaxDownloadFileSize |
Specifies the maximum size of a file, in megabytes, that can be downloaded. | 0 |
No |
| Output Directory | OutputDirectory |
Sets the base output directory to use when uploading files. If this message property is set to an empty string then the output directory is treated as empty, meaning that the user's home directory is used for the output directory. |
dir1/dir2 |
No |
| Base Filename | BaseFilename |
Sets the base filename to use when generating the filename for uploaded files. If this message property is set then it must not contain an empty value since an output filename is mandatory. If no output filename can be determined the outgoing message will be sent to the error queue. Unlike most other configuration properties, it is possible to set this value dynamically using the message property even when the communication point is configured in static mode. |
reports |
No |
| Filename Suffix | Suffix |
If this message property is set to an empty string then there will be no suffix in the upload file's name. Unlike almost all other configuration properties, it is possible to set this value dynamically using the message property even when the communication point is configured in static mode. |
txt |
No |
| Duplicate Filename Behaviour | DuplicateBehavior |
Determines how duplicate filenames are handled by the communication point:
If it is set to an empty string or an invalid value then the statically configured mode is used instead. |
rename |
No |
| Append Date/Time | AppendDateFormatForOutputFile |
Determines if the current date andtimeisappendedto the target filename prior to an upload:
If set to an empty string or an invalid value then the statically configured mode is used instead. If the date/time is appended, it will always be in the format This option is ignored if the duplicate filename behavior mode is configured to append to an existing file if a duplicate is found, as appending the current date/time is not allowed in this scenario. |
appendDateTime |
No |
| Append Date/Time Format | AppendDateTimeFormat |
Defines the date-time format when the date-time is appended to the filename. The default date-time format is yyyy-MM-dd-HH-mm-ss-SSS and is used if this property is left blank. The format should follow the specification in SimpleDateFormat in Java. |
|
No |
| Use Temp Files | TemporaryFileUsage |
Determines if temporary files will be used during uploads:
If set to an empty string or an invalid value then the statically configured mode is used instead. This option is ignored if the duplicate filename behavior mode is configured to append to an existing file if a duplicate is found, as temporary files are not allowed in this scenario. |
useTempFiles |
No |
| Before Send Commands | BeforeSendCommands |
A property list is used to configure the custom commands. Each entry in the property list is comprised of two parts separated by a pipe character: the error action, and the command. The following error actions are supported:
You must provide both an error action and a non-empty command. If any errors are detected in the configuration, then the outgoing message or trigger is sent to the error queue immediately. |
|
No |
| After Send Commands |
|
A property list is used to configure the custom commands. Each entry in the property list is comprised of two parts separated by a pipe character: the error action, and the command. The following error actions are supported:
You must provide both an error action and a non-empty command. If any errors are detected in the configuration, then the outgoing message or trigger is sent to the error queue immediately. |
|
No |
| Directory Navigation Mode | DirectoryNavigationMode |
Specifies whether to use FTP commands to traverse the target directory path and create the target directory if required during the file upload, or perform a direct file upload to the target directory:
|
|
No |