IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > FTP > Reference > Outbound configuration properties

Managed (J2C) connection factory properties

Managed connection factory properties are used by the adapter at run time to create an outbound connection instance with the FTP server.

You can set the managed connection factory properties using the external service wizard and can change them by using the IBM Integration Designer Assembly Editor, or after deployment through the IBM BPM administrative console.

The following table lists the managed connection factory properties. A complete description of each property is provided in the sections that follow the table. For information about how to read the property details tables in the sections that follow, see Guide to understanding property details .

The external service wizard refers to these properties as managed connection factory properties and the IBM BPM administrative console refers to them as (J2C) connection factory properties.

Managed connection factory properties
Property name Description
In the wizard In the administrative console
Adapter ID

AdapterID

Identifies the adapter instance for PMI events and for logging and tracing.

Custom parser class name property customParserClassName Specifies the fully qualified class name of the custom parser used to parse the ls –l output.
Data channel protection level dataProtectionLevel Specifies the protection level of a data channel in case of FTPS protocol.
Default target file name filename Specifies the name of the file to be used during outbound operations.
Maximum retries on connection failure connectionRetryLimit Specifies the number of times the adapter attempts to connect to the FTP server to reestablish the connection.
Directory outputDirectory Specifies the output directory in the FTP server.
Verify output directory access permission isPermissionCheckEnabled Specifies if the access permissions for the output directory must be verified before performing the outbound operation.
Disguise user data as "XXX" in log and trace files HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
Enable server verification enableServerVerification Enables the remote server verification for SFTP protocol
Encoding used by FTP server EISEncoding Specifies the encoding of the FTP server.
FTPS connection mode ftpsConnectionMode

Specifies the FTPS connection mode used to set up connection to the FTPS server.

Host key file hostKeyFile The absolute path of the host key file that contains the host keys of the trusted servers
Host name hostName Specifies the host name of the FTP server.
Host name secondServerHostName Specifies the host name of the second FTP server.
Host name SocksProxyHost Specifies the name of the workstation that is used as a proxy server.
Keystore file keyStorePath Specifies the path of the keystore that contains the private key entries.
Keystore password keyStorePassword Specifies the password used to encrypt the keystore.
Key password keyPassword Specifies the password used to encrypt the key.
Keystore type keyStoreType Specifies the type of the keystore.
Passphrase property passPhrase Used for enhanced security by encrypting the private key
Password Password Specifies the password of the user with privileges to connect to the FTP server and perform FTP operations.
Password SecondServerPassword Specifies the password of the Second FTP server to which the file is transferred during a server to server file transfer outbound operation.
Password socksProxyPassword Specifies the password used to authenticate the proxy server.
Port number portNumber Specifies the port number of the FTP server.
Port number secondServerPortNumber Specifies the port number of the second FTP server.
Port number socksProxyPort Specifies the port number of the proxy server.
Private key file privateKeyFilePath Private key used to authenticate to the secure shell server.
Protocol protocol Specifies if the connection to the FTP server is normal FTP or secure FTP.
Protocol secondServerProtocol Specifies the protocol used to connect to the second server.
Connection retry interval connectionRetryInterval Specifies the time interval between attempts to reconnect to the FTP server if the connection fails
Second Server Directory secondServerDirectory Specifies the directory path of the second FTP server to which the ServerToServerFileTransfer outbound operation is performed.
Sequence file fileSequenceLog Specifies the full path of the file where the sequence number is stored for the outbound Create process.
Staging directory stagingDirectory Specifies the directory that the file is first created in to.
Truststore file trustStorePath Specifies the path of the truststore file that contains the certificates of the FTPS servers trusted by the adapter.
Truststore password trustStorePassword Specifies the password of the truststore.
User name secondServerUserName Specifies the user name of the second FTP server to which the file is transferred during a server to server file transfer outbound operation.
User Name socksProxyUserName Specifies the user name used to authenticate to the proxy server.
User name username Specifies the name of the user.
Enable remote verification enableRemoteVerification Used to verify if the host system requesting the data transfer to or from the FTP server is the same host system on which the adapter is running.


Adapter ID (AdapterID)

This property identifies a specific deployment or instance of the adapter.

Adapter ID details
Required Yes
Default 001
Property type String
Usage This property identifies the adapter instance in the log and trace files, and also helps identify the adapter instance while monitoring adapters. The adapter ID is used with an adapter-specific identifier, FTPRA, to form the component name used by the Log and Trace Analyzer tool.

For example, if the adapter ID property is set to 001, the component ID is FTPRA001.

If you run multiple instances of the same adapter, ensure that the first eight characters of the adapter ID property are unique for each instance so that you can correlate the log and trace information to a particular adapter instance. By making the first seven characters of an adapter ID property unique, the component ID for multiple instances of that adapter is also unique, allowing you to correlate the log and trace information to a particular instance of an adapter.

For example, when you set the adapter ID property of two instances of WebSphere Adapter for FTP to 001 and 002. The component IDs for those instances, FTPRA001 and FTPRA002, are short enough to remain unique, enabling you to distinguish them as separate adapter instances. However, instances with longer adapter ID properties cannot be distinguished from each other. If you set the adapter ID properties of two instances to Instance01 and Instance02, you will not be able to examine the log and trace information for each adapter instance because the component ID for both instances is truncated to FTPRAInstance.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


Custom parser class name property (customParserClassName)

Fully qualified class name of the custom parser used to parse the ls –l output. Only used when the ls –l output deviates from standard output.

Custom parser class name property characteristics
Required No
Default None
Property type String
Globalized No


Data channel protection level (dataProtectionLevel)

This property specifies the protection level of the data transferred over the data channel. It specifies the type of data channel protection that the adapter and the server use.

Protection Buffer Size (PBSZ) and Data Channel Protection level (PROT) commands are issued by the adapter before opening a data channel to specify the protection level on the data channel. By default, the adapter issues the “PBSZ 0” command before issuing the PROT command.

Data channel protection level property characteristics
Required No
Possible values

Private - Data is transferred in encrypted form
Clear - Data is transferred as clear text

Default Private - Data is transferred in encrypted form
Property type String
Usage

This property is used for selecting the protection level for the data channel. Following are the protection values:

  • Private – Indicates that the data transfer will be integrity and confidentiality protected.
  • Clear – Indicates that the data channel will carry the raw data of the file transfer between the adapter and the server without any security.

Globalized No
Bidi supported No


Default target file name property (filename)

Specifies the name of the file that is used during outbound operations.

Default target file name property characteristics
Required Yes
Default Yes
Property type String

Usage

Use the WebSphere Application Server environment variable to represent the file name directory. Specify the name of the environment variable within braces, preceded by a $ symbol.

For example: ${FILENAME}. See Defining WebSphere Application Server environment variables.

Globalized No


Directory property (outputDirectory)

The property specifies the output directory in the FTP Server that the outbound operation is performed on. If the value of the Directory is set to <HOME_DIR>, the adapter performs the outbound operations in your home directory.

The value of output directory property accepts both the absolute and relative paths of the directory. If the value does not start with a forward slash, the adapter considers the path to be relative to your home directory.

Directory property characteristics
Required Yes
Default <HOME_DIR>
Property type String

Usage

You can use a WebSphere Application Server environment variable to represent the output directory. Specify the name of the environment variable in braces, preceded by a $ symbol.

For example: ${OUTPUT_DIRECTORY}. See Defining WebSphere Application Server environment variables.

Globalized Yes


Verify output directory access permission property (isPermissionCheckEnabled)

This property specifies if the access permissions for the output directory must be verified before performing the outbound operation.

Verify output directory access permission property characteristics
Required No
Possible values

True
False

Default True
Property type Boolean
Usage If the property is set to True, the adapter verifies the access permissions for the output directory before performing the outbound operation. The adapter requires the necessary permission to perform the listing operation on the parent directory.

If the property is set to False, the access permissions are not verified. As the access permissions are not verified and if the necessary access permissions are not set for the output directory, the outbound operation fails.

This property must be set to false, if you are using an FTP server that locks the user's home directory, and your output directory is the same as the user's home directory. Because, the adapter cannot verify permissions without moving to the parent directory of the user's home directory.

Globalized No


Disguise user data as "XXX" in log and trace files (HideConfidentialTrace)

This property specifies whether to replace user data in log and trace files with a string of X's to prevent unauthorized disclosure of potentially sensitive data.

Disguise user data as "XXX" in log and trace files details
Required No
Possible values

True
False

Default False
Property type Boolean
Usage If you set this property to True, the adapter replaces user data with a string of X's when writing to log and trace files.

For inbound processing, the value of this property is set at the resource adapter level. For outbound processing, the value can be set both at the resource adapter level and the managed connection factory level. After you use the external service wizard to configure the adapter for outbound processing, you can set the resource adapter and managed connection factory properties independently. If you use the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure that you set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Encoding used by FTP server property (EISEncoding)

Encoding of the FTP server. Use this value to set the encoding for the control connection to the FTP server.

Specify any Java-supported encoding set for this attribute.

Encoding used by FTP server property characteristics
Required No
Default None
Property type String
Globalized No


Enable server verification property (enableServerVerification)

This property is used to enable the remote server verification for SFTP protocol.

Enable server verification property details
Required No
Possible values

True
False

Default False
Property type Boolean
Usage

When this property is set to:

  • True, server authentication is enabled
  • False, server authentication is disabled

The adapter checks for the HostKeyFile property in the path of the file that contains the host keys of the trusted servers.

Globalized No
Bidi supported No


Enable remote verification property (enableRemoteVerification)

When a client connects to the FTP server, two kinds of connections or channels are established; a command connection (also known as control connection), and a data connection. The command connection is the one through which the FTP commands are sent (and replies to these commands received) to the server and the data connection is the channel through which the data transfer takes place between the client and the server.

This property is used to verify if the host system requesting the data transfer to or from the FTP server is the same host system on which the adapter is running.

The verification is done while establishing a data connection to perform data transfer.

This property is applicable only to FTP and FTPS protocols.

Enable Remote verification property characteristics
Required No
Possible values

True
False

Default True
Property type Boolean
Usage

This property verifies if the data connection and the control connection are from the same host system. By default, the remote verification property is set to TRUE by the FTP server.

When this property is set to:

  • True, during run time, the adapter checks if the data connection is established with the same host as the control connection. If the data connection is established from a different host than the control connection, then an exception is thrown and the connection fails.
  • False, remote verification is not performed.

Disabling the remote verification leads to low security. Precaution must be taken before disabling the remote verification.

Globalized No
Bidi supported No


FTPS connection mode property (ftpsConnectionMode)

This property is used to specify the connection mode when establishing a connection with the FTPS server. The WebSphere Adapter for FTP now supports both Implicit and Explicit connection modes. This property is used when you select either FTP over secure sockets layer (SSL) protocol or FTP over transport layer security (TLS) protocol.

FTPS connection mode property characteristics
Required No
Possible values

Explicit
Implicit

Default Explicit
Property type String
Usage

This property represents the mode used to connect to the FTPS server.

When this property is set to:

  • Explicit connection mode, initially the connection is established as a normal FTP connection. To send sensitive information, such as password the adapter switches to a secure FTP connection by issuing an AUTH command.

    The default port for Explicit connection mode is 21.

  • Implicit connection mode, the connection is established as a secure FTP connection. All communications between the adapter and the server continues in a secure mode. There is no exchange of clear text information between the Adapter and the server.

    The default port for Implicit connection mode is 990.

Globalized No
Bidi supported No


Host key file property (hostKeyFile)

This property provides the absolute path of the host key file that contains the host key of the trusted servers.

Host key file property characteristics
Required This property has to be specified if the EnableServerVerification property is enabled.
Default No default value
Property type String
Usage The adapter uses this property to verify the host key of the remote server with the host keys of the trusted servers specified in this file.
Globalized Yes
Bidi supported No


Host name property (hostName)

Host name of the FTP Server to which the connection is established during an outbound operation.

Host name property characteristics
Required Yes
Default None
Property type String
Globalized Yes


Maximum retries on connection failure (connectionRetryLimit)

This property specifies the number of times the adapter will attempt to reestablish a connection to the FTP server, when the adapter encounters an error related to the outbound connection.

If connection timeout is configured at the FTP server, the appropriate values for connectionRetryLimit and connectionRetryInterval needs to be set. The values for properties should be set so that the adapter retries the outbound request automatically if any connection error occurs due to timeout.

Maximum retries on connection failure property characteristics
Required No
Possible values Integers equal to and greater than zero
Default 0
Property type Integer
Usage

When this property is set to:

0

  • The adapter does not attempt to reconnect to the FTP server, if an error occurs during startup or while establishing a connection.

  • The adapter does not verify if the connection to the FTP server is valid when there is an outbound request at run time.

>0

  • The adapter attempts to reconnect to the FTP server for the specified number of times, if an error occurs during startup or while establishing a connection.

  • The adapter verifies if the connection to the FTP server is valid when there is an outbound request at run time. If the connection is not valid, it is terminated and a new connection is created to process the request.

    If the adapter fails to establish a connection after trying for the specified number of times, a connection error is generated.

    If the adapter is successful in reestablishing the connection, the outbound operation is completed.

Globalized No
Bidi supported No


Host name property (secondServerHostName)

Host name of the second FTP Server to which the connection is established during an outbound operation.

Host name property characteristics
Required Yes
Default None
Property type String
Usage Contains the host name or IP address of the FTP server, for example, 9.20.13.159
Globalized Yes


Host name property (socksProxyHost)

Host name of the workstation that is used as a proxy server through which the adapter requests are routed to the FTP server.

Host name property characteristics
Required No
Default None
Property type String
Globalized Yes


Keystore file property (keyStorePath)

This property specifies the path of the keystore that contains the private key entries.

Keystore file property characteristics
Required No
Default No default value
Property type String
Usage This property specifies the absolute path of the keystore file on the adapter machine (on which the adapter is running). The keystore file contains the private key entry of the FTPS client. It is also accompanied by a certificate chain for the corresponding public key. The keystore data is used to authenticate the clients identity while establishing an SSL connection.
Globalized No
Bidi supported No


Keystore password property (keyStorePassword)

This property specifies the password used to encrypt the keystore.

Keystore password property characteristics
Required No
Default No default value
Property type String
Usage This property specifies the password of the keystore. It is used to check the integrity of the keystore data.

If the value is not specified, integrity check will not be executed. It is applicable only if the protocol value is set to FTP over SSL or FTP over TLS.

Globalized Yes
Bidi supported No


Key password property (keyPassword)

This property specifies the password used to encrypt the key.

Key password property characteristics
Required No
Default No default value
Property type String
Usage This property specifies the password of the key used to recover the key from the keystore. The property is applicable only if the protocol value is set to FTP over SSL or FTP over TLS.
Globalized Yes
Bidi supported No


Keystore type property (keyStoreType)

This property specifies the type of keystore.

Keystore type property characteristics
Required No
Possible values JKS and PKCS12
Default JKS
Property type String
Usage This property specifies the type of the keystore. It is applicable only if you select FTP over SSL or FTP over TLS as the protocol. This property is also applicable for the type of the truststore.
Globalized No
Bidi supported No


Truststore file property (trustStorePath)

This property specifies the path of the truststore file that contains the certificates of the FTPS servers trusted by the adapter.

Truststore file property characteristics
Required This property is required only if you set the protocol as FTP over SSL or FTP over TLS
Default No default value
Property type String
Usage This property specifies the absolute path of the truststore file on the adapter machine (on which the adapter is running). The truststore file contains the certificates of FTPS servers trusted by the adapter and is used to authenticate the servers identity while establishing an SSL connection.
Globalized No
Bidi supported No


Truststore password property (trustStorePassword)

This property specifies the password of the truststore.

Truststore password property characteristics
Required No
Default No default value
Property type String
Usage This property specifies the password for the truststore. It is used to check the integrity of the truststore data.

If the value is not specified, the integrity check will not be executed. It is applicable only if the protocol value is set to FTP over SSL or FTP over TLS.

Globalized Yes
Bidi supported No


Passphrase property (passPhrase)

This property is used for enhanced security by encrypting the private key.

Passphrase property property characteristics
Required No
Default No default value
Property type String
Usage Used for enhanced security. It protects the private key by encrypting it in an SFTP configuration.
Globalized Yes
Bidi supported No


Password property (password)

Specifies, the password of the user with privileges to connect to the FTP server and perform FTP operations.

Password property characteristics
Required No
Default None
Property type String
Globalized Yes


Password property (secondServerPassword)

Specifies the password of the Second FTP server to which the file is transferred during a server to server file transfer outbound operation.

Password property characteristics
Required No
Default None
Property type String
Globalized Yes


Password property (socksProxyPassword)

Specifies the password used to authenticate the proxy server.

Password property characteristics
Required No
Default None
Property type String
Globalized Yes


Port number property (portNumber)

Specifies the port number of the FTP server through which the connection is established during an outbound operation.

Port number property characteristics
Required Yes
Default 21 for FTP and FTPS in Explicit mode, 990 for FTPS in Implicit mode, and 22 for SFTP.
Property type Integer
Globalized No


Port number property (secondServerPortNumber)

Specifies the port number of the second FTP server through which the connection is established during an outbound operation.

Port number property characteristics
Required Yes
Default 21 for FTP, 990 for FTPS.
Property type Integer
Globalized No


Port number property (socksProxyPort)

Specifies the port number of the proxy server through which the adapter requests are routed to the FTP server.

Port number property characteristics
Required No
Default 1080
Property type Integer
Globalized No


Private key file property (privateKeyFilePath)

This property enables you to browse and select the private key, which is used to authenticate to the secure shell server.

Private key property characteristics
Required No
Default None
Property type String
Usage Absolute path of the file which contains the private key. Used to authenticate the user to the secure shell server.
Example c:\temp\key.ppk
Globalized Yes
Bidi supported No


Protocol property (protocol)

Specifies the protocol that determines whether the connection to be established is a normal FTP connection or a secure FTP connection.

For example:

Normal connection: FTP

FTP over SSL connection: FTPS_SSL

FTP over TLS connection: FTPS_TLS

SSH-File Transfer Protocol connection: SFTP

Protocol property characteristics
Required Yes
Default FTP
Property type String
Globalized No


Protocol property (secondServerProtocol)

Specifies the protocol used to establish a connection to the second server. The FTP protocol is used in establishing the connection.

Protocol property characteristics
Required Yes
Default FTP
Property type String
Globalized No


Connection retry interval (in milliseconds) (connectionRetryInterval)

This property specifies the time interval between attempts to reconnect to the FTP server if the connection fails.

Connection retry interval (in milliseconds) property characteristics
Required No
Possible values Integers equal to and greater than 0
Default 60000
Unit of measure Milliseconds
Property type Integer
Usage

This property is applicable only if the value of the property “Maximum retries on connection failure” is set to greater than 0.

When the adapter encounters an error while establishing a connection to the FTP server, this property specifies the time interval the adapter waits between attempts to reestablish a connection.

Globalized No
Bidi supported No


Second Server Directory property (secondServerDirectory)

Specifies the directory of the second FTP server to which the ServerToServerFileTransfer outbound operation is performed. This is the remote event directory to which the file is transferred.

Second Server Directory property characteristics
Required No
Default None
Property type String
Usage The directory located on the FTP server and used in outbound operation represents the absolute path of the FTP directory. It does not contain any host name or URL information.

For example: /home/usr/output.

Globalized Yes


Sequence file property (fileSequenceLog)

Specifies the full path of the file where the sequence number will be stored for outbound Create processing.

When the FileSequenceLog property is specified, the adapter generates a unique sequence number to insert into the file name when processing the Create operation.

The sequence of numbers will continue to increment after multiple adapter restarts.

The sequence number is inserted into the file name in the following format:

filename.number.extension

For example Customer.3.txt

When the FileSequenceLog property is not specified or contains an invalid value, no sequence number is generated.

Sequence file property characteristics
Required No
Default None
Property type String
Usage

Important: Unless they are part of a cluster, it is not recommended that two adapter instances access the same sequence file, because concurrent requests result in delay while processing batch requests.

Globalized No


Staging directory property (stagingDirectory)

During an outbound create operation, a file is first created in the staging directory before it is moved to the directory specified in the DirectoryPath property. The staging directory is also used for the Append and Overwrite operations, where the specified file is copied to StagingDirectory (if present), then appended or overwritten with content and moved back to the original specified directory. If the StagingDirectory is not present, the operation is run in the actual required directory. When you work with a staging directory you can avoid file writing conflicts, which can occur when multiple users are reading the file or while the file is being overwritten during an append and update operation.

The value of staging directory property accepts both the absolute and relative paths of the directory. If the value does not start with a forward slash, the adapter considers the path to be relative to the home directory of the user.

Staging directory property characteristics
Required No
Default None
Property type String

Usage

You can use a WebSphere Application Server environment variable to represent the staging directory. Specify the name of the environment variable in braces, preceded by a $ symbol.

For example: ${STAGING_DIRECTORY}. See the topic on Defining WebSphere Application Server environment variables in this documentation for more information.

Globalized Yes


User name property (secondServerUserName)

Specifies the user name of the second FTP server to which the file is transferred during a server to server file transfer outbound operation.

User name property characteristics
Required No
Default None
Property type String
Globalized Yes


User Name property (SocksProxyUserName)

Specifies the user name used to authenticate the proxy server.

User Name property characteristics
Required No
Default None
Property type String
Globalized Yes


User name property (Username)

Specifies the name of the user with privileges to connect to the FTP server and perform FTP operations. You do not need to specify a value for this attribute if the User name is included in the URL specified in the FtpUrl property.

User name property characteristics
Required No
Default None
Property type String
Globalized Yes

Outbound configuration properties


Related tasks:

Generate the service