FTP Configuration

This setting controls the selection logic of the data connection. By default this value is True and the adapter will attempt to determine the best IP for the data connection based on the returned value from the server. It is recommended to leave this value set to True unless there is a reason to disable it.

In many cases FTP servers are not configured to return a valid public IP in the PASV response. When SSL/TLS is used any NAT done by the firewall cannot occur and the result is the client may receive an IP that is not accessible.

This setting is designed to allow the connection to succeed in as many cases as possible. When the IP for the data connection is received from the server the adapter will inspect the value. If the received value is not within the known private IP ranges the adapter will use it, assuming it is a valid public IP. If the received value is a private IP the adapter will instead assume the data connection should be established to the same IP as the command connection (true in almost all cases).

When this setting if False, the adapter will not perform any checks on the received value. When set to False UseRemoteHostAddressForPassive is applicable.

In some cases, the server may return a directory entry format that can not be automatically parsed by the adapter. In this case the full entry format can be seen in the log when the TransportLog's LogMode field is set to Verbose. You can then use this property to define a regular expression to parse the entry. The value of this setting is specified in the following format:

A,B,C,X=Y|RegEx

• FileName
• FileSize
• FileTime
• IsDir

Since group X represents the IsDir value, the user must specify Y to indicate what value that group must have in order for IsDir to be true.

Take for instance a simple entry in this format:

22 Test.txt

2,1,-1,-1|([0-9]+)\s(.*)

As seen in the above example -1 can also be specified as the integer value. When this is specified that field is ignored.

If true, the file on the server will be deleted in accordance with the option selected in DeleteMode even if the message is suspended.

The default value is False.

This may be set to the location of a file on disk that will hold the names of files that were previously downloaded from the server. On each PollingInterval the adapter will check to see if the file on the server exists in this list. If the file exists in this list, it is determined that the file was previously downloaded and is not downloaded on the current polling interval. The list is automatically updated on each polling interval.

If a file name is added to the DownloadCacheFile and is not seen on the server again within DownloadCacheFileDuration minutes, it will be removed from the cache. This can prevent the download cache file from growing too large in certain cases.

The default value is 0, meaning that files will never be removed.

This setting is only applicable if DownloadCacheFile is set.

This setting is used in conjunction with DownloadCacheFile, and is only available on the receive adapter. If DownloadCacheFile is enabled, this setting can be used to control how the receive adapter uses the download file cache information when deciding whether to download a file again. (Similar to the "Enable Timestamp Comparison" property on Microsoft's FTP BizTalk Adapter.)

If this is set to False, the receive adapter will not download a file again if the cache contains any information about it (that is, if it has been downloaded before).

If this is set to True, the receive adapter will check the metadata of the remote file against its cached metadata, and will download the file again if any of the metadata differs.

When this option is true the adapter will ignore any empty files when downloading from the server.

The default value is false.

Note: This is only applicable to the Receive adapter.

By default, the adapter will download all available files (matching any filemasks) when polling the target directory. To limit the number of files that will be downloaded in a single poll, set this to the maximum number.

Note that to avoid downloading the same subset of files each poll, either DownloadCacheFile or DeleteMode should also be used.

If set to "TRUE" the adapter will store the file sizes of the remote files between polling intervals. If the file size does not change between polling intervals it will be downloaded and removed from the list. Otherwise it will be skipped for that interval. For example, if this option is set to TRUE, the adapter would do the following on the first two polling intervals:

Interval 1: The adapter will record the file size of the remote files.

Interval 2: The adapter will compare the recorded file size with the current file size of the remote files. If the file size has not changed then the adapter will download the file. If the file size has changed then the adapter will record the new file size but take no other actions.

If set to "FALSE" the adapter will not perform a directory listing to check for the presence of the file on the server before uploading the file.

NOTE: This setting is only applicable to the FTP Transmitter.

This setting overrides the overrides the default behavior of the adapter, causing it to ignore the normal message data and upload the file indicated. Likewise, the parsed local filename is used instead of the value in the RemoteFile property.

This may also be set to a local directory when Download is set to True in the send adapter.

When set to use active mode (Passive = False), the adapter uses any available port to listen to incoming connections from the server. You can override this behavior by setting PortRange to a value containing the range of ports the adapter will be listening to.

The range is provided as start-end, for instance: "1024-" stands for anything higher than 1024, "1024-2048" stands for ports between 1024 and 2048 inclusive, "4000-4010, 50000-50010" stands for ports between 4000 and 40010 or between 50000 and 50010.

After downloading a file, the file on the server may be renamed using this setting. This rename action will take place after the batch submission to BizTalk. If you need to perform actions on a file before this, use the AfterGet property. This setting is used in conjunction with RenameMode to conditionally rename a file. For instance, to rename a file after it has been successfully submitted to BizTalk set the Other property of the adapter like so:

RenameTo=%SourceFileName%.done

This setting controls when the value specified by RenameTo is used. If RenameTo is not specified, this setting has no impact. By default, downloaded files are only renamed after being successfully submitted to BizTalk (a value of 1). Possible values are:

During download, it may be necessary for the file on the server to be renamed. After the download is complete the file will be renamed back to the original name.

During upload, it may be necessary for the RemoteFile to be written to a temporary file name. For example, some business process may be set up to expect a specific file extension. Using this setting will allow the adapter to upload the file without the remainder of the process attempting to pick up the incomplete file.

When set to True (default), the adapter will ask the server to reuse the existing DI SSL session. When set to False, a new SSL session will always be created for the DI connection.

When set to True, the adapter will reuse the PI SSL session when creating the DI connection. The default value for this configuration setting is False, in which case, the adapter will create a separate SSL session for the DI connection.

When set, the adapter will send the CCC command to the server requesting a clear (unprotected) command channel.

When this is set, the adapter will use a clear (unprotected) data channel by sending the PROT C command to the server.

This is only applicable when UseSimpleDirList is set to true. When UseSimpleDirList is true, the adapter issues the command "NLST -F <filemask>". The -F parameter tells the server to omit folder names from the response. Some server do not support the -F parameter. To disable the use of the -F parameter set UseFSwitch to False. The default value is True.

When this is set to True the adapter will list files in the directory using the MLSD command. This command is an extension to the protocol which defines a more standardized and reliable directory listing format. Not all servers support this command. The default value is False.

The adapter will send the PROT P command to the server explicitly indicating that the data channel will be protected when this is set. This only applies when the SSLStartMode is set to sslImplicit.

This setting is only used when Passive is true. When this is set to false (default), the adapter parses the remote host to send replies to from the previous response from the server. If this is true, the adapter uses the value at FTPServer instead.

The default value is false. When set to true the adapter will issue the "MODE Z" command to the FTP server. This will enable deflate compression so all data transferred is first compressed either by the server (when downloading) or by the adapter (when uploading). Note that not all servers support this feature.

The default value is 7. Valid values are from 0 to 9. A higher value indicates a higher compression level is used. This is only valid when UseModeZ is set to True.

This setting is used to download a file from an orchestration using the send adapter. It is only applicable to the send adapter. In situations where you want to initiate the download of a file instead of using a receive adapter you can configure the send adapter to download the file.

In this case the adapter should be used as a solicit response adapter. Because a solicit response port can return only one message, you can only download one file at a time with the SFTP, SCP, FTP, and WebDAV send ports. To do this you'll need to set the DownloadSingleFile configuration setting to true. For instance:

Message_2 = Message_1;
Message_2(nsoftware.BizTalk.SFTP.SSHUser) = "test";
Message_2(nsoftware.BizTalk.SFTP.SSHPassword) = "test";
Message_2(nsoftware.BizTalk.SFTP.SSHHost) = "server";
Message_2(nsoftware.BizTalk.SFTP.SSHAcceptServerHostKeyAcceptAny) = true;
Message_2(nsoftware.BizTalk.SFTP.RemotePath) = "temp";
Message_2(nsoftware.BizTalk.SFTP.RemoteFile) = "test.txt";
Message_2(nsoftware.BizTalk.SFTP.Other) = "DownloadSingleFile=true";

Note: You can also set DeleteAfterDownload in the Other property for FTP, SFTP, and WebDAV transfers to delete the file on the server once the download is complete. DeleteAfterDownload is not applicable to SCP. This can be done by setting one configuration setting per line in the Other property:

Message_2(nsoftware.BizTalk.SFTP.Other) = "DownloadSingleFile=true\r\nDeleteAfterDownload=true";

It is also possible to download multiple files with the send adapters. To do this you can not use a solicit response port. You must use a one way send port. In this case set the LocalFile setting to the directory to which you'd like to download the files and set Download to true.

This setting is used to download multiple files using the send adapter. It is only applicable to the send adapter. In situations where you want to initiate the download of files instead of using a receive adapter you can configure the send adapter to download the files. It is similar in use to DownloadSingleFile.

To do this you can not use a solicit response port. You must use a one way send port. In this case set the LocalFile setting to the directory to which you'd like to download the files.

This setting is used in conjunction with either Download or DownloadSingleFile. It is only applicable to the send adapter. When the send adapter is configured to download a file this setting can also be specified to delete the file from the server after it is downloaded.

If an error occurs after an upload has started, the partial upload may remain on the remote server after the error is handled. If this setting is True, the send adapter will delete the partial upload while handling the error. The default value is False.

This is only applicable to the send adapter.

This setting is used to list the files in a remote directory on the server from an orchestration using the send adapter. It is only applicable to the send adapter. In situations where you want to list the contents of a directory you can configure the send adapter to do so.

In this case the adapter should be used as a solicit response adapter. In your orchestration after referencing the SFTP, FTP, or WebDAV adapter you can set the message context properties to configure the adapter. To specify that the adapter should list the directory set the Other property to ListDirectory=true. For instance:

Message_2 = Message_1;
Message_2(nsoftware.BizTalk.SFTP.SSHUser) = "test";
Message_2(nsoftware.BizTalk.SFTP.SSHPassword) = "test";
Message_2(nsoftware.BizTalk.SFTP.SSHHost) = "server";
Message_2(nsoftware.BizTalk.SFTP.SSHAcceptServerHostKeyAcceptAny) = true;
Message_2(nsoftware.BizTalk.SFTP.RemotePath) = "temp";
Message_2(nsoftware.BizTalk.SFTP.RemoteFile) = "*.txt";
Message_2(nsoftware.BizTalk.SFTP.Other) = "ListDirectory=true";

<Directory name="temp">
  <Directory name="subDir1"/>
  <Directory name="subDir2"/>
  <File name="file1.txt">
    <Size>size</Size>
    <Time>time</Time>
  </File>
  <File name="file2.txt">
    <Size>size</Size>
    <Time>time</Time>
  </File>
  <File name="file3.txt">
    <Size>size</Size>
    <Time>time</Time>
  </File>
</Directory>

Note: The SFTP adapter returns additional CTime and ATime elements representing the CreationTime and AccessTime. CreationTime is only supported on servers that support SFTP protocol version 4 or higher. To enable the adapter to use version 4 or higher you can set ProtocolVersion to "4".

If set to true, the adapter will reuse the context if and only if the following criteria are met:

• The target host name is the same.
• The system cache entry has not expired (default timeout is 10 hours).
• The application process that calls the function is the same.
• The logon session is the same.
• The instance of the adapter is the same.

This minimum cipher strength largely dependent on the security modules installed on the system. If the cipher strength specified is not supported, an error will be returned when connections are initiated.

Please note that this setting contains the minimum cipher strength requested from the security library.

Use this setting with caution. Requesting a lower cipher strength than necessary could potentially cause serious security vulnerabilities in your application.

Used to enable/disable the supported security protocols.

Not all supported protocols are enabled by default (the value of this setting is 4032). If you want more granular control over the enabled protocols, you can set this property to the binary 'OR' of one or more of the following values:

Note: TLS 1.1 and TLS1.2 support are only available starting with Windows 7.

Note: Enabling TLS 1.3 will automatically set UseInternalSecurityAPI to True.

This setting specifies whether the transport log contains the full certificate chain. By default this value is False and only the leaf certificate will be present.

If set to True all certificates returned by the server will be present in the transport log. This includes the leaf certificate, any intermediate certificate, and the root certificate.

Note: When UseInternalSecurityAPI is set to True this value is automatically set to True. This is needed for proper validation when using the internal provider.

The following flags are defined (specified in hexadecimal notation). They can be or-ed together to exclude multiple conditions:

The enabled cipher suites to be used in SSL negotiation.

By default, the enabled cipher suites will include all available ciphers ("*").

The special value "*" means that the adapter will pick all of the supported cipher suites. If SSLEnabledCipherSuites is set to any other value, only the specified cipher suites will be considered.

Multiple cipher suites are separated by semicolons.

Example values when UseInternalSecurityAPI is False (default):

// The "Other" property could contain ONE of the following lines:
SSLEnabledCipherSuites=*
SSLEnabledCipherSuites=CALG_AES_256
SSLEnabledCipherSuites=CALG_AES_256;CALG_3DES

• CALG_3DES
• CALG_3DES_112
• CALG_AES
• CALG_AES_128
• CALG_AES_192
• CALG_AES_256
• CALG_AGREEDKEY_ANY
• CALG_CYLINK_MEK
• CALG_DES
• CALG_DESX
• CALG_DH_EPHEM
• CALG_DH_SF
• CALG_DSS_SIGN
• CALG_ECDH
• CALG_ECDH_EPHEM
• CALG_ECDSA
• CALG_ECMQV
• CALG_HASH_REPLACE_OWF
• CALG_HUGHES_MD5
• CALG_HMAC
• CALG_KEA_KEYX
• CALG_MAC
• CALG_MD2
• CALG_MD4
• CALG_MD5
• CALG_NO_SIGN
• CALG_OID_INFO_CNG_ONLY
• CALG_OID_INFO_PARAMETERS
• CALG_PCT1_MASTER
• CALG_RC2
• CALG_RC4
• CALG_RC5
• CALG_RSA_KEYX
• CALG_RSA_SIGN
• CALG_SCHANNEL_ENC_KEY
• CALG_SCHANNEL_MAC_KEY
• CALG_SCHANNEL_MASTER_HASH
• CALG_SEAL
• CALG_SHA
• CALG_SHA1
• CALG_SHA_256
• CALG_SHA_384
• CALG_SHA_512
• CALG_SKIPJACK
• CALG_SSL2_MASTER
• CALG_SSL3_MASTER
• CALG_SSL3_SHAMD5
• CALG_TEK
• CALG_TLS1_MASTER
• CALG_TLS1PRF

// The "Other" property could contain ONE of the following lines:
SSLEnabledCipherSuites=*
SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA
SSLEnabledCipherSuites=TLS_DHE_DSS_WITH_AES_128_CBC_SHA;TLS_DH_ANON_WITH_AES_128_CBC_SHA

• TLS_DHE_DSS_WITH_AES_128_GCM_SHA256
• TLS_DHE_DSS_WITH_AES_256_GCM_SHA384
• TLS_DHE_DSS_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA
• TLS_DHE_DSS_WITH_AES_128_CBC_SHA256
• TLS_DHE_DSS_WITH_AES_256_CBC_SHA
• TLS_DHE_DSS_WITH_AES_256_CBC_SHA256
• TLS_DHE_DSS_WITH_DES_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
• TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
• TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA
• TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA
• TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
• TLS_DHE_RSA_WITH_DES_CBC_SHA
• TLS_RSA_WITH_AES_256_GCM_SHA384
• TLS_RSA_WITH_AES_128_GCM_SHA256
• TLS_RSA_WITH_3DES_EDE_CBC_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA
• TLS_RSA_WITH_AES_128_CBC_SHA256
• TLS_RSA_WITH_AES_256_CBC_SHA
• TLS_RSA_WITH_AES_256_CBC_SHA256
• TLS_RSA_WITH_DES_CBC_SHA
• TLS_RSA_WITH_RC4_128_MD5
• TLS_RSA_WITH_RC4_128_SHA

If SSLEnabledProtocols is configured to use TLS 1.3 the following values are supported:

• TLS_AES_128_GCM_SHA256
• TLS_AES_256_GCM_SHA384

SSLEnabledCipherSuites is used together with SSLCipherStrength.

This setting specifies the allowed server certificate signature algorithms when UseInternalSecurityAPI is True and SSLEnabledProtocols is set to allow TLS 1.2.

When specified the adapter will verify that the server certificate signature algorithm is among the values specified in this setting. If the server certificate signature algorithm is unsupported the adapter will fail with an error.

The format of this value is a comma separated list of hash-signature combinations. For instance:

// The "Other" could contain ALL of these lines:
UseInternalSecurityAPI=true
SSLEnabledProtocols=3072
TLS12SignatureAlgorithms=sha1-rsa,sha1-dsa,sha256-rsa,sha256-dsa

In order to not restrict the server's certificate signature algorithm, specify an empty string as the value for this setting, which will cause the signature_algorithms TLS 1.2 extension to not be sent.

This setting specifies a comma separated list of (EC)DHE groups that are supported for key exchange. The values are ordered from most preferred to least preferred. The following values are supported:

• "ecdhe_secp256r1" (default)
• "ecdhe_secp384r1" (default)
• "ecdhe_secp521r1"
• "ffdhe_2048" (default)
• "ffdhe_3072" (default)
• "ffdhe_4096"
• "ffdhe_6144"
• "ffdhe_8192"

The default value is ecdhe_secp256r1,ecdhe_secp384r1,ffdhe_2048,ffdhe_3072. This setting is only applicable when SSLEnabledProtocols includes TLS 1.3. Note that groups of larger size require more computational resources and will impact performance.

This setting holds a comma separated list of allowed signature algorithms. Possible values are:

• "rsa_pkcs1_sha256" (default)
• "rsa_pkcs1_sha384" (default)
• "rsa_pkcs1_sha512" (default)

If AbsoluteTimeout is set to True, any method which does not complete within Timeout seconds will be aborted. By default, AbsoluteTimeout is False, and the timeout is an inactivity timeout.

The LocalHost configuration contains the name of the local host as obtained by the Gethostname() system call, or if the user has assigned an IP address, the value of that address.

In multihomed hosts (machines with more than one IP interface) setting LocalHost to the value of an interface will make the adapter initiate connections (or accept in the case of server adapters) only through that interface.

If the adapter is connected, the LocalHost configuration shows the IP address of the interface through which the connection is made in internet dotted format (aaa.bbb.ccc.ddd). In most cases, this is the address of the local host, except for multihomed hosts (machines with more than one IP interface).

When true, the socket will send all data that is ready to send at once. When false, the socket will send smaller buffered packets of data at small intervals. This is known as the Nagle algorithm.

By default, this config is set to false.

By default the adapter will use the system security libraries to perform cryptographic functions. When set to False calls to unmanaged code will be made. In certain environments this is not desirable. To use a completely managed security implementation set this setting to True. Setting this to True tells the adapter to use the internal implementation instead of using the system's security API.

Note: This setting is static. The value set is applicable to all adapters used in the application.

When this value is set the product's system DLL is no longer required as a reference, as all unmanaged code is stored in that file.

If persisted connections are enabled and PersistedConnectionTimeout is set to a positive value, the connection will be kept alive for that number of minutes after a message transmission. If no other messages are sent over that connection during the timeout period, the adapter will disconnect from that server.

Note: the default value is 0. This value means that the connection will be kept alive unless the server disconnects it due to idling.