FTP


WebSphere Adapter for FTP documentation

WebSphere Adapter for FTP provides the ability for applications in BPM, and WebSphere Enterprise Service Bus, to access data only accessible through an FTP server without the need for special coding. The adapter works with the FTP server by sending requests to it and by monitoring and responding to events that occur in it.


Overview of WebSphere Adapter for FTP

With WebSphere Adapter for FTP, you can create integrated processes that use IBM Business Process Manager or WebSphere Enterprise Service Bus to access files managed by an FTP server. You do not need to know the details of FTP communication or protocols.

After configuration, the adapter provides services in a Service-oriented architecture (SOA) implementation, to send and retrieve files. The adapter is part of a module that is deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.

The adapter exposes a service interface that hides the mechanics of how the data, or operations are obtained or run. Services outside of the module interact with the adapter instead of directly interacting with the FTP server, so authentication details (such as user name and password) that you provide when you set up a module are shielded from services outside of the module.

The module, which you create with the external service wizard in IBM Integration Designer, is a reusable unit designed to perform a specific inbound or outbound service. Each module uses a consistent interface and standard business objects, so applications consuming the service do not have to understand the lower-level details of the FTP server.

The following illustration shows how the adapter functions as part of an SOA implementation.

Figure 1. Adapter overview


Feedback


Hardware and software requirements

The hardware and software requirements for WebSphere Adapters are provided on the IBM Support website.

To view hardware and software requirements for WebSphere Adapters, see http://www.ibm.com/support/docview.wss?uid=swg27006249.


Additional information

The following links provide additional information you might need to configure and deploy your adapter:


Feedback


Technical overview

WebSphere Adapter for FTP provides the means for services running on IBM Business Process Manager or WebSphere Enterprise Service Bus to communicate with one or more FTP servers.

The services are contained in a module, which consists of both a project in IBM Integration Designer and a unit of deployment to IBM Business Process Manager. The module is packaged and deployed to IBM Business Process Manager as an enterprise archive (EAR) file.

The module contains components, which are the actual services, imports and exports. Imports identify services outside of a module, making them callable from within the module. Exports allow components in a module to provide their services to external clients. Imports and exports require binding information, which specifies the means of transporting the data from the modules. The assembly editor in IBM Integration Designer sets up the imports and exports, lists the supported bindings, and simplifies their creation.


Feedback


Outbound processing

WebSphere Adapter for FTP supports outbound request processing. When the adapter receives a request, which is sent in the form of a business object from the module, it processes the request to perform an operation on the files in the remote file system and returns the result, when applicable, in a business object.

The following illustration shows the outbound processing flow for WebSphere Adapter for FTP.

Figure 1. Outbound processing flow


Feedback


Supported operations

An operation is an action the adapter can perform on remote file systems accessible through an FTP server during outbound processing. The name of the operation typically indicates the type of action the adapter takes, such as Create or Append.

The adapter is supported only for files and all outbound operations fail when they are performed at a folder level. To perform any operation on folders, use the ExecuteFtpScript outbound operation. During outbound processing, WebSphere Adapter for FTP supports the following operations.



Related reference:

Wrapper and interaction specification properties

Feedback


Append operation

The Append operation appends content to a specified file.

The file with the specified name in the specified directory of the FTP server is appended with the content sent in the request.

If the file to be appended exists, the content is appended, and the file name is sent back to the calling component indicating a successful response.

If the staging directory is specified, the file to be appended is copied from the specified output directory to the staging directory, and the content is appended to that file in the staging directory. The appended file is then moved back to the original directory.

If the file to be appended does not exist and the CreateIfFileNotExist property is set to True, the adapter creates a file.

If the file to be appended does not exist, a RecordNotFound exception is sent to the calling component.


Feedback


Create operation

The Create operation creates a file with the specified name in the given directory of the FTP server.

If a temporary file name is specified, a file is created with a temporary file name on the FTP server. After the file is created at a remote location, it is renamed to the target file name. The Temporary file name property is available in the interaction specification properties.

The file can be created in a staging directory and then sent to the actual directory. If a staging directory is not specified, the file is directly created in the actual directory.

Use the properties FileInLocalDirectory and LocalArchiveDirForCreate, you can create files in the local directory and local archive directory, respectively.

The content of the file can either be sent as part of the request or it can be retrieved from the local file system. When the file content is received as part of the request, the adapter provides the option to archive the file on the adapter workstation before creating it.

After the file is created, the file name is sent back to the calling component to indicate the file was created successfully. If the file to be created exists, a DuplicateRecord exception is sent, and the file is not created. The existing file is not overwritten.



Related reference:

Wrapper and interaction specification properties

Feedback


Generating a file sequence

The adapter supports the generation of a file sequence during an outbound Create operation. The FileSequenceLog property is introduced to specify the full path of the file where the sequences are stored.

A sequence file is a file used to store the sequence number. The adapter obtains the sequence number in this file for the current operation and increments the existing number by one and updates the file. When a sequence file is created, the file does not contain any data and the adapter starts generating the sequence number from 1.

For every request, the adapter reads the sequence number, increments it by 1 and then updates the sequence file. A sequence number is used while creating a request file in the target folder. If the number is not valid, for instance, if it is non-numeric, consists of special characters, or is zero or negative, the adapter starts the sequence again from 1. The adapter uses the existing sequence number in the file when the adapter is restarted.

The sequence number is the only content in the sequence file used for an outbound create operation regardless of any directory or file name. When you open the sequence file for editing, the content appears in Unicode format.

When a value is specified for the FileSequenceLog property, the adapter generates file sequence numbers, and appends to the file name of the files that it creates. The sequence number accepts the following format: $FILENAME.$SEQUENCE_NUMBER.$FILE_EXT. For example, if HostName = localhost and Filename = Customer.txt, the output files are Customer.1.txt, Customer.2.txt, Customer.3.txt, and so on. The sequence number continues to increment after multiple adapter restarts.

When the adapter is operating in a stand-alone mode, the value for the FileSequenceLog property must be in a file on the local file system. When the adapter is operating in a clustered environment, the value for the FileSequenceLog property must be in a file on the mapped drive accessible by all the clusters. The adapter must have write permission for the sequence log file or an IOException takes place.

The file sequence number can be reset either by deleting the entry in the file or by deleting the file. A new sequence begins at 1. When the FileSequenceLog property and GenerateUniqueFilename property are both enabled, the GenerateUniqueFilename property value takes precedence, and the FileSequenceLog property is not generated.

You can generate the file sequence names. To generate file sequence names, specify:

  1. The sequence file, which is the full path of the file where the sequence numbers are stored.
  2. The default target file name.

The adapter generates a file name that consists of the default target file name with the sequence number appended to it. If the default file name has an extension, the sequence number is appended before the extension. For example, if the default file name is Customer.txt on the managed connection factory, the output file names that are created are Customer.1.txt, Customer.2.txt, and so on.

The adapter performs the following steps to support compatibility with earlier versions:

  1. The adapter reads the sequence file and checks for an entry of the form path = sequenceNumber.

  2. If such an entry exists in the file, the sequence file contains the data in the form supported by WebSphere Adapter for FTP version 6.1.
  3. The adapter gets the highest sequence number available from all the entries.
  4. This number is used to create a file.
  5. The adapter increments the number and overwrites the entire file with the new number.

Two different managed connection factories must not access the same sequence file. Also, two different adapter instances must not access the same sequence file unless they are part of a cluster, in which case they access a shared sequence file.


Feedback


Generating unique file names

The Create operation supports the generation of unique file names when the GenerateUniqueFile property is set to true. When the GenerateUniqueFile property is enabled or the FileSequenceLog property is set and if a temporary file name is provided, the file is directly created with the target file name.

For Append and Overwrite operations, the GenerateUniqueFile property is deprecated from version 6.2 onwards. Even if the value is set for this property, the adapter considers the value as False.

With WebSphere Adapter for FTP, version 7.5, you can specify the prefix and/or suffix for the adapter to generate file names. For the file name to be unique, an eight digit random number is generated to be part of the file name. The format of the file name is <prefix> <random number> <suffix>. By default, the file name does not have an extension. The following example illustrates this format: If the prefix is abc and the suffix is .xyz, then the generated file name is abc72953168.xyz.

If both the prefix and suffix are not specified, the adapter generates the file name as follows:

The properties that control the generation of unique file names are located in two places:

The properties in the business object take precedence over the properties in the interaction specification.

The adapter does not support both the GenerateUniqueFile and StagingDirectory options simultaneously.


Feedback


Delete operation

The Delete operation deletes a specified file.

The file in the specified directory is deleted on the FTP server and the adapter returns True to the calling component to indicate the file was successfully deleted. If the file to be deleted does not exist, a RecordNotFound exception is sent to the calling component.


Feedback


ExecuteFTPScript operation

The commands contained in an FTP script file are run in the adapter workstation. The operation runs only the commands that are supported by the FTP server. If the operation fails, the adapter sends an FTPFileExecuteFTPScript exception to the calling component.

The script file must not contain connection-related commands such as open because the adapter uses an established connection to run the commands.

The directory must be specified in the DirectoryPath and the file name in the FileName property.

If the commands in the script file are to be run in a particular directory on the FTP server, then the script file must first contain the command to change to that directory.

A list of commands runs and their reply strings are returned to the calling component. The adapter also supports parameter substitution in the FTP script file (replacing parameters %1, %2 with actual values). The values are sent as part of the request.

The script file must contain commands that are supported by the selected protocol.


Feedback


Exists operation

The Exists operation checks to see whether a specified file exists.

If the file name in the request exists in the specified directory or any of the sub folders, the adapter returns True and the full path of the file to the calling component. If a file with the same name exists in more than one directory, the adapter returns True and the full path of the first file found to the calling component.

If the file name does not exist, or the directory does not exist, the adapter returns False to the calling component.


Feedback


ServerToServerFileTransfer operation

This operation transfers the specified file from one FTP server directory to another FTP server directory. After the file has been transferred successfully, true is returned to the calling component.

Both the FTP servers must support the ServerToServerFileTransfer operation and a connection must be established between the FTP servers and the workstation where the adapter is running.

If the request does not contain all necessary information about the two servers, the adapter sends an FTPFileServerToServerFileTransfer exception to the calling component.

The ServerToServerFileTransfer operation does not support FTPS (FTP over SSL and FTP over TLS) or SFTP protocol.


Feedback


List operation

The List operation lists the file names in the specified directory.

All the file names and directories specified in the request are returned to the calling component.

If only the directory is specified, all the file names in the directory are retrieved and sent as a response to the calling component.

If the specified directory does not exist, a RecordNotFound exception is sent to the calling component.


Feedback


Overwrite operation

The Overwrite operation overwrites the specified file with the content specified in the request.

After the content is overwritten, the file name is sent back to the calling component indicating a successful response.

The file to be overwritten is copied from the specified directory to the staging directory, if specified, and the content is overwritten for that file in the staging directory. The file is then moved back to the specified directory. If a staging directory is not specified, the content is overwritten on the file in the specified directory.

If the file to be overwritten does not exist, and the CreateIfFileNotExist property is set to True, the adapter creates a file.

If the file to be overwritten does not exist, a RecordNotFound exception is sent to the calling component.


Feedback


Retrieve operation

The Retrieve operation retrieves the content of the specified file and returns it in the form of a business object.

The file content is split based on the SplittingFunctionClassName and SplitCriteria properties. The file content is transformed into a business object based on the configured data handler.

After the content of the file is retrieved it is sent as the response. The file content can either be sent back to the calling component or saved to the local file system. If the file to be retrieved does not exist, a RecordNotFound exception is sent to the calling component.

The adapter provides an option to delete the file from the FTP server directory after it is retrieved through the DeleteOnRetrieve property.

The adapter supports an option to archive the file on the FTP server before it is deleted through the ArchiveDirectoryForRetrieve property.

While configuring the Retrieve operation for data transformation, create custom retrieve wrappers like CustomerRetrieveWrapper or CustomerRetrieveWrapperBG, or OrderRetrieveWrapper or OrderRetrieveWrapperBG, and use the wrapper for the output type in the operation window.

For a Retrieve operation without data transformation, the default wrapper RetrieveResponseWrapper is used.

The compatibility with an earlier version may use RetrieveResponseWrapper for retrieving XML data with data transformation.


Feedback


Outbound data transformation

Data transformation during outbound communications refers to the process by which the adapter transforms business objects into an event record created in a native format, such as bytes or a string. The adapter uses adapter-specific data binding and data handlers to accomplish data transformation.

Data transformation permits external applications to send and receive data in a format they can understand and process easily. The data bindings and data handlers the adapter uses to create the event record from the corresponding attributes in a business object are configured through the external service wizard in IBM Integration Designer.


Data bindings

Data bindings are essentially maps that define how a business object must be formatted. Data bindings are responsible for reading the fields in a business object and filling the corresponding fields in an event record. The adapter uses the FTPFileBaseDataBinding data binding during outbound communication.

During outbound communications, the data binding uses the following fields in a business object, and populates their equivalent fields in an event record with their values:

For data that does not require transformation, the adapter conducts pass-through processing because data passes through the system without being altered.


Data handlers

In addition to data bindings, data transformation requires the use of a data handler. Data handlers perform the conversions between a business object and a native format. From version 6.2 onwards, WebSphere Adapter for FTP provides the following data handlers:


Feedback


Authentication using connection specification properties

WebSphere Adapter for FTP uses connection properties either through Managed Connection Factory properties or a Javaâ„¢ Authentication and Authorization Services (JAAS) alias.

To change the connection properties used for authentication with either one of these authentication methods, you can change the connection properties through the BPM administrative console and restart the Java EE application or change the JAAS security settings.

In addition to the methods explained, the connection parameters can also be specified through the ConnectionSpec properties. The ConnectionSpec properties are used by an application component to pass connection-related properties.

Based on the protocol used in the Managed Connection Factory, you can specify the relevant ConnectionSpec properties for the outbound request. If you specify both ConnectionSpec properties and Managed Connection Factory properties during run time, the adapter uses the values specified in the ConnectionSpec properties to create a connection and ignores the values in the Managed Connection Factory properties. For more information about security settings, see Security.

The following table lists the ConnectionSpec properties for different protocols:

ConnectionSpec properties

FTP FTPS SFTP

  • userName
  • password

  • userName
  • password
  • trustStorePath
  • trustStorePassword
  • keyStorePath
  • keyStorePassword
  • keyPassword
  • keyStoreType

  • userName
  • password
  • privateKeyFilePath
  • passphrase
  • hostKeyFile

To configure the adapter to create an FTP server connection, see Passing the connection parameters dynamically.




Previous topic: Set interaction specification properties and generating the service


Next topic: Passing the connection parameters dynamically


Related tasks:

Passing the connection parameters dynamically

Create an interface

Create a Java component

Feedback


Inbound processing

WebSphere Adapter for FTP supports inbound processing of events. The adapter polls a file system associated with an FTP server for events at specified intervals. Each time a file is created in the event directory, the adapter tracks it as an event. When the adapter detects an event, it requests a copy of the file, converts the file data into a business object, and sends it to the consuming service.

The following illustration shows the inbound processing flow for the adapter.

Figure 1. Inbound processing flow

The adapter polls files from the event directory of the FTP server at regular intervals based on the FTPPollFrequency property. When a file arrives in the event directory, the adapter reads the entire file and downloads it to a local event directory on the adapter workstation. The adapter downloads the files from the FTP server, one file at a time, and cannot download all the files simultaneously. After the file is downloaded, the adapter either archives the file in the FTP server in an archive directory given by the FTPArchiveDirectory property or deletes it based on your configuration. The event directory, archive directory, poll frequency, and poll quantity (the number of files to poll in a single poll cycle) are all configurable properties.

If the Remote directory is set to <HOME_DIR>, the adapter polls for event files in user's home directory. The value of an event directory property accepts both the absolute and relative paths of the directory. If the value does not begin with a forward slash (/), the adapter considers the path to be relative to the home directory of the user.

For example, if the value in the remote directory property is set to ftpuser/event, the adapter considers this to be the path relative to the home directory. If the home directory is set to “/usr/ftp", then the adapter polls the directory /usr/ftp/ftpuser/event for event files.

After the business objects are successfully posted to the export, the events in the local staging directory are either archived in an archive directory on the local file system or deleted, based on your configuration. The adapter must archive or delete the events or they are polled again.

Inbound event processing consists of the following steps:

  1. FTP server generates events in the form of files.
  2. The adapter polls the event directory.
  3. The files are downloaded to the adapter.
  4. The files are split based on the SplittingFunctionClassName and SplitCriteria properties. The event file is split into several chunks and each chunk is posted to the export separately. This reduces memory loading during event processing.

    • If splitting is done based on a delimiter, the class that performs this function and the split criteria are provided.

    • If splitting is done based on file size, the class name that performs this function is provided.

    • If splitting is done based on other criteria, you must provide your own file splitting class.

  5. The adapter sends information about the location of the polled document and the host name of the system where the file was retrieved, to the export. A function selector invokes the configured data binding, converts the text record into a business object.


Processing of files using FTP scripts

In addition to processing the files downloaded from the event directory during polling, the adapter can also be used to process the files downloaded using the FTP scripts.

You can specify the scripts to be run before or after polling the event directory using the properties, Run FTP script file before downloading files property (ftpScriptFileExecutedBeforeInbound) and Run FTP script file after downloading files property (ftpScriptFileExecutedAfterInbound). The script files can contain FTP commands, such as mget and get, to download the files from the remote directories on the FTP server to the local event directory of the machine where the adapter is installed. The adapter processes the files that are downloaded to the local event directory configured in the activation specification properties and delivers the processed business objects to the consuming service.

Following is an example of a script: 

lcd C:\FTPAdapter\localevent
cd /ftpDir1
mget *.txt
cd /ftpDir2
get abc.xml

Where, C:\FTPAdapter\localevent is the local event directory of the adapter, and ftpDir1 and ftpDir2 are directories that exist on the FTP server. The adapter executes the script and downloads the files to the local event directory. The adapter then processes the files and delivers it to the consuming service.

  1. You must copy the files downloaded using the script to the configured local event directory for the adapter to process it. Use the FTP command lcd to change the local working directory to the localEventDirectory before you download any files using the script.
  2. The files downloaded to the local event directory using the commands, mget or get will be deleted from the FTP server by the adapter after you download the files. This is to ensure the files are not downloaded again during the next poll cycle.

  3. Use the script file to download the files only from remote directories and not from the event directory of the adapter.


Supported inbound operation

The adapter supports the default emitFTPFile operation, during inbound configuration.


Event file locking

File locking behavior is operating system dependent. In Windows, if any of the files being polled by the adapter from the event directory are in use by another application and in the process of being copied to the event directory, they are not made available to the adapter for processing.

However, in UNIX environments, such as AIX , there is no file locking mechanism that prevents applications from accessing files that are being written to. A file that is being copied to the event directory by another application is made available to the adapter for processing, causing erroneous results. There is no platform-independent way in Javaâ„¢ to check whether a file is being written to.

To prevent this situation from occurring, you can first copy the event file to a staging directory and then move it to the event directory using the move command. Some sample UNIX scripts are provided as part of the adapter. The script file named CheckIfFileIsOpen.sh is available in the Unix-script-file folder in the adapter installer.


Rule-Based filtering of events

The adapter supports the rule-based filtering of events, which is optional for inbound processing. You can filter the events based on multiple rules. You can define a combination of these rules, group them with Boolean logic, and filter the events using the following metadata:

For example, you can use FileName "MatchesFilePattern" *.txt, where FileName is the property type, "MatchesFilePattern" is the operator and "*.txt" is the value.

Though using the rule is optional and specifying an event file mask is mandatory, the rule takes a higher precedence over the event file mask, when both a rule and an event file mask are specified. Event file mask is effective only when there is no rule specified. By default, an event file mask has "*.*" as the default value.

Rule-based filtering does not support the logical "OR" operator values between multiple rules.

Adapter does not support rule-based filtering when the EIS is on MVSâ„¢ platform.

Metadata filtering properties

Property Valid operators Value Prerequisites
FileName Matches_File_Pattern For example: *.txt Nil
Matches_RegExp Java Regular Expression  
FileSize Greater than, Less than, Greater than or equal to, Less than or equal to, Equal to, Not equal to. Numeric value in Bytes. For example: 10000 Nil
LastModified Greater than, Less than, Greater than or equal to, Less than or equal to, Equal to, Not equal to.

Select the &apos;Equal to&apos; operator when you choose the days of a week.

Day of the week or Time. For example : MONDAY or 20:41:10 Nil
END-OF-RULE END-OF-RULE END-OF-RULE Nil



Related tasks:

Set deployment and runtime properties


Related reference:

Custom file splitting

Activation specification properties

Feedback


File retrieval

During inbound processing, you can manage the retrieval of the files by using the Time interval for polling unchanged files property. This property helps you to retrieve only those files which are not changed during the specified time interval. If the time difference between the last modified timestamp and the current system time is greater than the value set in FileUnchangedTimeInterval, then such files are polled. In addition to verifying the files that are not changed during the time interval, the adapter also verifies if there is a change in the file size before polling a file in the event directory. However, the value of the file size attribute is dependant on the operating system and the FTP server used.


File retrieval based on time interval

The Time interval for polling unchanged files property monitors the changes to files in the event directory for the specified time interval. When you configure this property, the adapter polls the files that have not undergone any change during the time interval. Although the adapter polls the files that are currently being edited, any unsaved content will not be processed during the event processing. This configuration prevents occurrence of any erroneous results.

When the adapter polls the event directory, it uses this property to check if a file has been modified during the specified time interval. The adapter uses the lastModifiedtimestamp value of the files to determine if a file has changed during the time interval.

The adapter retrieves the unchanged files in their present state and the changed files from their last saved state. See the Time interval for polling unchanged files property details.

During an inbound operation, the adapter does not support files with the following file name format:


Feedback


Function selectors

During inbound processing, a function selector returns the appropriate operation to be called on the service. You choose a function selector when you configure the adapter for inbound processing in the external service wizard.

The adapter provides the following three function selectors:


FilenameFunctionSelector

FilenameFunctionSelector is a rule-based function selector that provides object name resolution based on regular expressions that map to file names. A regular expression is a string used to describe or match a set of strings according to certain syntax rules.

The following table shows examples of matching rules, where a rule consists of the ObjectName and Rule fields.

Examples of matching rules for FilenameFunctionSelector

FileName ObjectName Rule
Customer0001.txt Customer CUST.*TXT
2231ORZ93.z21 Order [0-9]*OR[A-Z][0-9]{2}.*
2231ORZ93.z21 Order *OR.*

The rules in the second and third rows resolve to the same name. However, the rule in the second row requires a specific sequence of numbers and letters in order for the file name to match. The rule in the third row resolves anything with the characters “OR” in the file name. The character combination “.*” indicates that any character can occur any number of times.

To generate a native function name, the function selector adds emit as the prefix to the object name that you provide. For example, if the object name is Customer, the function selector returns the function name as emitCustomer. The object name must be the payload object name, for example, Customer or Order, and not the wrapper or business graph name. For pass-through scenarios, use FTPFile as the object name.

You can configure FilenameFunctionSelector with multiple rules, each containing an object name, and a regular expression to match against the file name. If more than one rule matches, the function selector returns the object name based on the first matching rule. If no rule matches, the adapter generates an error. If no rules are present in the configuration, the function selector uses the function name emitFTPFile.

For a detailed explanation of the rules governing the use of regular expressions, see the Javaâ„¢ Class Pattern documentation at https://java.sun.com/j2se/1.4.2/docs/api/java/util/regex/Pattern.html.


EmbeddedNameFunctionSelector

EmbeddedNameFunctionSelector is used for content-specific business objects, where the object name is embedded in the event file. It returns the function name based on the required content data, and not on the wrapper. For example, if the content-specific business object is CustomerWrapperBG, the function returned by the function selector is emitCustomer.

This function selector must be configured with a data handler. The data binding must be the adapter-specific WrapperDataBinding, and it must be configured to use the same data handler that is configured with the function selector.


RootNameFunctionSelector

RootNameFunctionSelector is used only for global elements in business objects, where the global element name is the root element name in the event XML file. It returns the function name based on the global element name. For example, if the global element name is CustomerType1, the function returned by the root name function selector is ‘emit CustomerType1'.

RootNameFunctionSelector is used only for global elements with XML Datahandler or UTF8XMLDatahandler.

To use global Elements with Delimited Datahandler or FixedWidth Datahandler, use FilenameFunctionSelector instead of RootNameFunctionSelector.

RootNameFunctionSelector does not require a Datahandler configuration, as it does not depend on the data handler to determine the function name.


Feedback


Inbound data transformation

During inbound communications an adapter transforms an event record created in a native format, such as bytes or a string, into a business object. The process is called data transformation. The adapter uses an adapter-specific data binding and data handlers to accomplish the data transformation.

The data bindings and data handlers are configured in the external service wizard.


Data bindings

The adapter uses the data bindings to retrieve the fields from an event record created in a native format. Then populate the corresponding fields in a business object. The adapter uses the FTPFileBaseDataBinding data binding during inbound communication.

During inbound communications, the data binding uses the following fields from an event record and populates the corresponding business object attributes with their values:

For data that does not require transformation, the adapter conducts pass-through processing because data passes through the system without being altered.


Data handlers

In addition to data bindings, data transformation requires the use of a data handler. A data handler converts data from a native format into a business object. From version 6.2 onwards, the adapter provides the following data handlers:


Feedback


Passing files by reference

The adapter also supports a PassByReference feature, where only the event file name is sent to the export. The event file is appended with a time stamp and is available in the local archive directory. This feature should not be used with data transformation. While using this feature, if there are any data handlers configured then an exception occurs.

Use the Pass only file name and directory, not the content property to send only the file name and directory path to the end point.

Set the local archive directory to use this property.


Feedback


Splitting files

The inbound event processing mode supports an optional file splitting feature, where the event file is split into several business objects, also known as chunks. Each business object is posted to the export separately. This reduces memory loading during event processing. File splitting is performed based on either a delimiter or on a file size specified in the SplitCriteria property.

The adapter provides SplitBySize and SplitByDelimiter classes for file splitting. Optionally, you can provide a custom file splitter class and use it by providing the class name in the SplittingFunctionClassName property.


Splitting files by size

The splitting size is set in the SplittingFunctionClassName property.

Chunks refer to the resulting files after the file is split. When chunking is enabled, each chunk of the file is posted to the export separately. The number of business objects specified in the PollQuantity property is posted to the export. For example, if the value for PollQuantity is 3, then:

The number of business objects polled is 3.

The number of business objects received by the export is 3.

The adapter does not reassemble chunked data. It provides the information about the chunked data for an external application to merge the chunks. The chunking information is set in the chunkInfo property, which is contained in the business object. This information includes the chunk size in bytes, and the event ID. An example of an event ID is: 

AbsolutePathOfTheEventFileNameInLocalEventDirectory_/_yyyy_MM_dd_HH_mm_ss_SSS.
currentBONumber

With WebSphere Adapter for FTP, version 7.5, the event ID does not contain the total business object count, and hence it is not part of the chunk information. Optionally, you can add the total business object count in the chunk information by using the Include total business object count in the ChunkInfo property. See Include total business object count in the ChunkInfo (includeBOCountInChunkInfo).


Splitting files by delimiter

Delimiters are specified values, used for splitting the event files. The delimiter is specified in the SplitCriteria property.

The following rules apply when the delimiter is used:

Example 1: 

John Doe,123,Washington Ave,222-123-4567
Jane Smith,234,Washington Ave,222-123-4568
The separator is the end of line character. In this example you would specify \r\n for Windows, \r for Macintosh, and \n for UNIX.

Example 2: 

John Doe
123 Washington Ave
222-123-4567
####
Jane Smith
234 Washington Ave
222-123-4568
The separator is ####.

Example 3: 

ISAJohnDoe1*IBM************USA************
ISAJohnDoe2*IBM************USA************
ISAJohnDoe3*IBM************USA************
The separator or delimiter in this example is ISA and it is at the beginning of each record.


Feedback


Event store

The event store (event persistence table) is a persistent cache where events are saved until the adapter can process them. The adapter uses event persistence tables to track the inbound requests as they make their way through the system. Each time a file is created in the event directory, the adapter tracks the activity as an event, and updates the status of the event in the event persistence table. The status of each event is continually updated by the adapter for recovery purposes until the events are delivered to a configured export.

If the adapter detects there is no event persistence table, it automatically creates one when the module is deployed to the runtime environment. Each event persistence table created by the adapter is associated with a specific inbound module. The adapter does not support multiple adapter modules pointing to the same event persistence table.

When the adapter polls the FTP server, it creates an entry in the event persistence table for each event that matches the search criteria specified in the activation specification properties. The adapter records the status of each new entry as NEW. When the adapter sends the event to the function selector for data transformation, it deletes the entry from the event table.

When guaranteed event delivery is not required, the adapter can poll for events without the existence of an event persistence table.

The following figure illustrates the event management flow of the adapter.

Figure 1. Event management flow


Feedback


Event recovery

The adapter supports event recovery for inbound processing in case of abrupt termination. During event processing, the adapter persists the event state in an event persistence table located on the data source. You must set up this data source before you can create the event persistence table.

To use the recovery feature provided in BPM, you must set the value of the AssuredOnceDelivery property in the activation specification as True. If it is set to False, the failed events cannot be recovered. Duplicate events can be delivered if the AssuredOnceDelivery property is set to False. To improve performance, you can set the AssuredOnceDelivery property to False.


Feedback


Event store structure

The event persistence table is a persistent cache where events are saved until the adapter can process them.

The following table describes the event store structure.

Event persistence table structure

Column Name Type Description
EVNTID Varchar(255) A unique event ID for tracking purposes. The adapter uses this ID to track events during inbound processing.

The event ID consists of the file name, timestamp, and the current business object number.

Event ID format: AbsolutePathOfTheFile_/_TimeStamp.CurrentBOCount

EVNTSTAT Integer The status of the event. The adapter uses the status to determine whether an event is new or in-process.

Event status values:

NEWEVENT (0)

The event is ready to be processed.

FETCHED (3)

The adapter picked up the event for processing.

PROCESSED (1)

The adapter successfully processed and delivered the event.

FAILED (-1)

The adapter was unable to process this event due to one or more problems.
XID Varchar(255) Used by the adapter for assured event delivery and recovery.
EVNTDATA Varchar(255) Used by the adapter to mark the failed events as ARCHIVED to ensure they are not processed again during adapter startup or recovery.

BOSRTPOS

Long Indicates the start position of the file content of the business object corresponding to the event ID.

BOENDPOS

Long Indicates the end position of the file content of the business object corresponding to the event ID.

TIMESTMP

timestamp Indicates the time the event was picked up for processing.


Feedback


File store

When the adapter polls the event directory, an entry is created in the file table for each event file that matches the search criteria specified in the activation specification properties. The adapter uses the file table to track the inbound files. Each time a file is created, updated, or deleted, the adapter updates the status of the entry in the file table.

In a clustered environment, the adapter uses the file table for the following:

In addition, the file table enables the adapter to process large files (of any size).

The following figure illustrates the event and file management flow of the adapter. The adapter records the status of each entry as New.

Figure 1. Event and File management flow


Feedback


File store structure

The file table contains the entries for the files to be polled by the adapter. The entries in the table support the adapter to read only the file content required by the polling quantity. In addition, the last position of the file pointer after the partial read is recorded in this table.

The following table describes each file table column.

File table structure

Column name Type Description
FILENAME Varchar (255) Name of the event file to be processed.
FILESTAT Integer

Status of the file entry. The adapter uses the status to determine whether the file is a new event to be processed or if the event is being currently processed.

UNPROCESSED (0)

The new file is ready to be processed. WebSphere Adapter for FTP polls the event directory for files and creates an entry in the file table.

IN-PROCESS (1)

A file is in-process if the adapter is reading the file content. When the file status is 1, no other adapter is allowed to process the file. The timestamp is updated when the file is picked up for processing.

EVENTS UPDATED (2)

The adapter reads only the file content required by the polling quantity and generates the new events for the current set of business objects.

PROCESSED (3)

The file processing is complete and the event entries are generated in the event table for the business objects.

FAILED (4)

The adapter was unable to read the file because of an unexpected error. The file might be corrupted or invalid.

ARCHIVING (5)

The archiving process for this file is in progress.
LBOCOUNT Long Specifies the number of business objects that were processed until the file was previously read.
LREADPOS Long Indicates the end position of the file pointer up to the point where the file was previously read.
TIMESTAMP Timestamp Indicates the time when the file was picked up for processing.
LMDFTIME Timestamp Indicates the last modified time of the file.


Feedback


Event archive

Archived events are stored in the archive directory with a file extension specified in the FTPRenameExt property. Event archiving is an optional feature, which provides you with a record of all the events that have been processed. You can use this information to review whether the events were processed successfully.

Event archiving is used differently in different configurations:


Archive on MVS platforms

Multiple Virtual Storage (MVSâ„¢) operating systems do not support special characters such as an underscore in data set or recordset names. On Windows and UNIX platforms, use a time stamp in the original file name while archiving the file. This prevents duplicate file names in an archive folder, therefore, preventing the overwriting of an existing file. Use the following format for MVS systems:

Event File: Test Archived

file: Test.TSyyyyMM.TSDDHHMM.TSSsSss

Where:

yyyy year
MM month
DD date
HH hour
MM minutes
Ss seconds
Sss milliseconds

The data set or record set separator is . (decimal) on MVS platforms. The maximum number of . (decimals) allowed in a data set or record set is six. The data set or record set name must not exceed eight characters per . (decimal), and the total number of characters must not exceed 44. An example of a file name in this format is:

FTPRenameExt: ARCHIVE

Archived File: TEST.TS200304.TS290535.TS42234.ARCHIVE


Feedback


Business objects

A business object is a structure that consists of data, the action to be performed on the data, and additional instructions, if any, for processing the data. The data can represent either a business entity, such as an invoice or an employee record, or unstructured text.


How the adapter uses business objects

The adapter uses business objects to send data to or obtain data from the FTP server. During inbound operations, the adapter collects information from an event record created in a native format, convert it to a business object, and forward it to a service. For outbound operations, this process happens in reverse. The adapter receives a business object from a service, creates an event record from the details it finds in the business object, and then sends the event record to the FTP server.


How data is represented in business objects

Business objects are created using the business object editor in IBM Integration Designer, which provides a graphical view of your business objects. As shown in the following illustration, a business object consists of a set of fields and their values. This is a customer business object. As you can see, it records name, address, and phone number information for a customer record. This example uses string values, but many other values are supported by the business object editor.

Figure 1. How data is represented in business objects


How business objects are created

You can create business objects by using the external service wizard or the business object editor, both of which can be launched from IBM Integration Designer.

If you have defined XSD files using the business object editor before starting the external service wizard, the adapter creates business objects from these schemas. For instructions on how to use the business object editor to create business objects, see http://pic.dhe.ibm.com/infocenter/dmndhelp/v8r0mx/index.jsp. After you create your business objects, you can use the business object editor to define the hierarchy of the business objects.


Business graphs

During adapter configuration, you can optionally choose to generate a business graph. In version 6.0.2, each top-level business object is contained in a business graph, which includes a verb that an application can use to specify additional information about the operation to be performed. Beginning version 7.0, business graphs are optional; they are required only when you are adding business objects to a module created with an earlier version. If business graphs exist, they are processed, but the verb is ignored.



Related reference:

Business object information

Feedback


Global elements

Global elements are the globally defined schema elements, which can be reused by referencing them in other parts of the schema or from other schema documents.

WebSphere Adapter for FTP supports global elements in structured business objects. The adapter supports global elements of anonymous type and global elements of named type, with namespace as well as without namespace in schema business objects.

For more information see, Business object structure.


Feedback


Resume file transfer

WebSphere Adapter for FTP resumes the transfer of files that were interrupted due to an error in connection to the FTP server. When the connection is reestablished you can resume the transfer of files. The files are transferred from the point at which it was interrupted. This feature is useful when downloading or uploading large files.

During a create operation, if the connection to the FTP server breaks, the FTPFileTransferInterruptedException is returned by the adapter. To resume file transfer, a request must be resubmitted to the adapter. Set the ResumeFailedTransfer property to True in the wrapper object, for the adapter to resume the file transfer. The adapter, upon reestablishing the connection to the FTP server, resumes the transfer of the file being created on the FTP server.

The ResumeFailedTransfer property is applicable only for the outbound processing. You can resume a file transfer operation only for an outbound Create operation.

Similarly, for an inbound operation, the adapter tracks the files downloaded partially and resumes downloading the file after the connection is reestablished. The adapter saves the file with a “.partial” extension while downloading to the local event directory and renames the file to the original file after the file is completely retrieved to the local event directory.

The file for which the transfer was interrupted due to connection error must not be modified until the file is completely transferred to the FTP server. You cannot modify the partially uploaded or downloaded file created by the adapter, till the file transfer is complete.

  1. The FTP or FTPS server must provide support for the REST FTP command to resume the transfer of the file.

  2. You cannot resume a file transfer (operation) with the SFTP protocol.

See the ResumeFailedTransfer property details in Wrapper and interaction specification properties.


Feedback


WAS environment variables

When you configure the adapter for inbound or outbound processing using the external service wizard, you set values for various required local files and directories. You can later change these values in the deployed application from the BPM administrative console.

With IBM Business Process Manager version 6.2 and onwards, instead of hard coding values for directories and files, you can declare them as WebSphere Application Server environment variables, and specify the environment variable names when you run the external service wizard. When you deploy your application, the environment variable name is replaced with the actual value and used by the adapter.

To change the property value, you can change the environment variable in the administrative console.

WAS environment variables can be used for all string property values (not Boolean or integer variables) that are set in inbound and outbound configuration.

When you define a WAS environment variable, you specify:

See the topic Defining WAS environment variables Defining WAS environment variables for detailed information about how to create a WAS environment variable.



Related tasks:

Defining WAS environment variables

Feedback


External service wizard

The external service wizard in WebSphere Adapter for FTP is used to create services and to generate business objects from the selected objects. The wizard also generates the service artifacts that enable the adapter to run as a Service Component Architecture (SCA) component.


Feedback


Log and Trace Analyzer

The adapter creates log and trace files that can be viewed with the Log and Trace Analyzer.

The Log and Trace Analyzer can filter log and trace files to isolate the messages and trace information for the adapter. It can also highlight the adapter's messages and trace information in the log viewer.

The adapter's component ID for filtering and highlighting is a string composed of the characters FTPRA plus the value of the adapter ID property. 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 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 outbound processing, the adapter ID property is located in both the resource adapter and managed connection factory property groups. If you update the adapter ID property after using the external service wizard to configure the adapter for outbound processing, be sure to set the resource adapter and managed connection factory properties consistently. It prevents inconsistent marking of the log and trace entries. For inbound processing, the adapter ID property is located only in the resource adapter properties, so this consideration does not apply.

See the Adapter ID (AdapterID) property.


Feedback


Business faults

The adapter supports business faults, which are exceptions that are anticipated and declared in the outbound service description, or import. Business faults occur at predictable points in a business process, and are caused by a business rule violation or a constraint violation.

Although IBM Business Process Manager and WebSphere Enterprise Service Bus support other types of faults, the adapter generates only business faults, which are called faults in this documentation. Not all exceptions become faults. Faults are used only when the outbound operations are configured with response type. Faults are generated for errors that are actionable, that is, errors that can have a recovery action that does not require the termination of the application. For example, the adapter generates a fault when it receives a business object for outbound processing that does not contain the required data or when the adapter encounters certain errors during outbound processing.

The faults for a particular operation are enabled only if that operation has a response configured.


Fault business objects

The external service wizard creates a business object for each fault the adapter can generate. In addition, the wizard creates a WBIFault superset business object, which has information common to all faults, such as the message, errorCode, and primaryKeySet attributes as shown in Figure 1.

Figure 1. The structure of the WBIFault business object

The adapter enables you to declare faults. Manual configuration of faults is not required.


Feedback


Plan for adapter implementation

To implement the IBM WebSphere Adapter for FTP, you must plan for inbound and outbound processing and consider security and performance requirements.



Next topic: Configure the module for deployment

Feedback


Before you begin

Before you begin to set up and use WebSphere Adapter for FTP, you must possess a thorough understanding of business integration concepts, the capabilities, and requirements of the integration development tools and runtime environment you use.

To configure and use the adapter, you must understand and have experience with the following concepts, tools, and tasks:


Feedback


Prerequisites and Best Practices for using WebSphere Adapter for FTP


Recommended configuration settings

Configure timeout and connection pool settings

The adapter works best if the FTP server timeout settings and the WebSphere Application Server connection pool settings are tuned to suit the business needs.

Following are some example scenarios that explain the recommended configuration settings.

For more information about the timeout and connection pool settings, see http://pic.dhe.ibm.com/infocenter/wasinfo/v8r0/topic/com.ibm.websphere.nd.doc/info/ae/ae/udat_conpoolset.html.

Configure connection retry properties

The connectionRetryLimit, connectionRetryInterval, retryLimit, retryInterval are the additional properties that can be used to work around the known environment issues.

For example, if there is any known communication problem with the FTP server during an inbound processing:


UNIX style output format from FTP server

The adapter is designed to work with the FTP servers whose file listing output matches with the standard UNIX style output format. If the FTP server file listing does not match the UNIX style output format, you can change the FTP server settings. If the server settings cannot be changed, it is recommended that you configure the adapter with custom parsers to parse the FTP server file listing.

While configuring the adapter, you can use the Custom parser class name property in the external service wizard to specify custom parser class name. Click Browse under Additional configuration to select the custom parser class name from the list available. For more information about custom parsers, see Adapter customization with Custom Parser Class.


Set the right access permissions for the adapter

The adapter requires the right access permissions to connect and process the files at remote or local directories. If the access permissions are not set correctly, the adapter fails to connect to the target directories. For more information about checking the access permissions, see How to check for access permissions in an output, remote event, or remote archive directory?


Set the data connection mode

The data connection mode used by the FTP server during the file transfer is either active or passive.

Also, ensure the firewall(s) is not blocking the ports the adapter or FTP server is trying to use for the data connection.


Processing large volume of data

While processing large volume of data through the adapter, to improve the adapter performance, it is recommended that you periodically move or backup the files in the local and remote archive directory.


Use file masks

When multiple adapters are polling the same remote event directory on the FTP Server, to ensure that no two adapters are polling or accessing the same files, it is recommended specified different file masks for the adapters.


Sharing local event directory

When you use multiple adapters, it is recommended the adapter uses a unique local event directory and do not share a local event directory between the adapters. However, in a clustered environment with a HA Active-Active configuration, the same local event directory must be shared between the clustered application. See Adapter not applying the file mask during recovery.


File-based operations

WebSphere Adapter for FTP is a file-based adapter and cannot be used for folder-based operations. To perform any operation on folders, it is recommended that use the ExecuteFtpScript outbound operation.


Connect to FTP server

In an outbound processing, WebSphere Adapter for FTP connects only to a single FTP server. To connect to different FTP servers, it is recommended that you use multiple adapter instances.


Feedback


Firewall setting while using FTP server

The FTP server connection mode is set based on the firewall settings for the FTP server and the adapter.

While configuring the adapter, ensure the FTP server connection mode is set properly for the adapter to connect to the FTP server. If the property is not set based on the firewall settings for the FTP server and the adapter then the adapter fails to connect to the FTP server. For more information about setting the FTP server connection mode, see the dataConnectionMode property for inbound processing and outbound outbound processing.

If the adapter is behind the firewall, set the dataConnectionMode property value as passive. If the FTP server is behind the firewall, set the dataConnectionMode property value as active.


Feedback


Security

To protect the integrity of information between the FTP server and the adapter, you can configure the adapter with the following secure settings:


Feedback


Support for FTPS protocol

Data that travels across a network can be intercepted by third parties. When this data includes private information, such as passwords or credit card numbers, steps must be taken to make this data unintelligible to unauthorized users. Data encryption can be achieved using cryptographic protocols, such as secure socket layer (SSL) and transport layer security (TLS). When FTP protocol is used with SSL or TLS, the security mechanism is referred to as secure FTP or FTPS (Also known as FTP over SSL or FTP over TLS).

By configuring secure socket layers (SSL) or transport layer security (TLS), you protect the integrity of information sent between the FTP server and adapter. When the adapter is configured to work in secure FTP, both the control connection and data connection can be encrypted.


Secure socket layer (SSL)

Secure socket layer (SSL) is a network protocol used to transmit data in a secure mode. SSL protocol uses the public key cryptography technique to encrypt the data while transferring, and also ensures data confidentiality.


Transport layer security (TLS)

Transport layer security (TLS) is a protocol used for secure data transfer between the client and the server. It is the successor of the secure socket layer (SSL) protocol.


FTPS connection modes

The FTPS client can establish a connection with the secure FTP server in either implicit or explicit mode.

Implicit mode: In an implicit mode, the communication between the client and server is set up immediately in secure mode. The text information exchanged between the client and server is in an encrypted format. The default port for implicit mode is 990.

Explicit mode: In an explicit mode, the connection begins with an unencrypted FTP connection. When any sensitive information, such as password, needs to be sent, the client explicitly issues a request to switch to a secure FTP connection. After the successful SSL negotiation, a secure command channel is established between the client and the server.

Explicit mode works with the default port 21 and is compliant with RFC 2228 commands. RFC 2228 specifies the mechanism for authenticating connections and confidential data transfer between the client and server and this is referred to as explicit mode. The AUTH command is used for specifying the security mechanism for the explicit mode. The client sends an AUTH command (AUTH SSL/TLS) to the FTPS server and switches to a secure command connection.

By using the connection modes, the data protection level with which the data is transferred between the client and the server can be configured.


Data connection encryption

According to RFC 2228, Protection buffer size (PBSZ) and data channel protection level (PROT) commands are issued by the client to specify the protection level on the data channel.

Protection buffer size (PBSZ) is used to negotiate a maximum protected buffer size for the data connection. PBSZ command accepts a long value as an argument, and determines the maximum size of the buffer in which the encoded data is sent or received during data transfers.

FTP over TLS supports only PBSZ 0 to ensure the buffering of data does not takes place. PBSZ command with the argument value '0' indicates a streaming protocol and the data is transferred as a stream of data.

PROT command allows client or server negotiation for the security level data connection. RFC 2228 specifies the following four levels of protection:

  1. Clear (C): The Clear protection level indicates the data channel carries the raw data for the file transfer, with no security applied.
  2. Safe (S): The Safe protection level indicates the data is integrity protected.
  3. Confidential (E): The Confidential protection level indicates the data is confidentiality protected.
  4. Private (P): The Private protection level indicates the data is integrity and confidentiality protected.

FTP over TLS protocol supports only Clear and Private levels of data protection.


Server authentication

Server authentication is a check performed for a secure connection. While establishing an SSL connection to the FTPS server, the FTP client performs a server certificate validation against the certificates present in the client trust store. The client trust store contains the certificates of all servers that are trusted. If the required certificate of the server is found in the client trust store, then a connection is established.

If the certificate is not found in the client trust store, the server is considered as an untrusted server, an exception is generated, and a connection is not established with the FTPS server.


Client authentication

Client authentication is similar to server authentication, except the server requests a certificate from the client to verify if it is from a trusted client. The certificate has to be signed by a certificate authority trusted by the server. The client authentication requires a compatible FTPS server for authenticating. When a server requests a certificate, the client has the option to send a certificate. The server allows the connection if the client's certificate can be trusted.

The FTP server authenticates the client based on the public certificate while establishing an SSL connection. The client provides the public key during an SSL connection and is exchanged with the FTPS server, which authenticates the clients identity based on the certificates configured in the servers trusted certificates.

  1. Configure the adapter for FTPS protocol WebSphere Adapter for FTP supports connecting to an FTPS server using SSL or TLS protocol. WebSphere Adapter for FTP can be configured to connect to the FTPS server in either explicit or implicit mode. The adapter supports secure FTP using SSL v3.0 and TLS v1.0.
  2. Configure the adapter for FIPS 140-2 The federal information processing standard 140-2 (FIPS) is a United States government standard for cryptographic features like encryption, decryption, hashing (message digests), secure socket layers, transport layer security, Internet Protocol security, Secure shell, signatures, key exchange, and key or certificate generation used in software products and modules. If you are an user working with the United States government who must conform to the FIPS standard, you can configure the adapter to run in FIPS mode.



Related concepts:

Support for SFTP protocol


Related tasks:

Configure the adapter for FTPS protocol


Related reference:

Activation specification properties

Managed (J2C) connection factory properties

Feedback


Configure the adapter for FTPS protocol

WebSphere Adapter for FTP supports connecting to an FTPS server using SSL or TLS protocol. WebSphere Adapter for FTP can be configured to connect to the FTPS server in either explicit or implicit mode. The adapter supports secure FTP using SSL v3.0 and TLS v1.0.

To enable SSL, ensure the following prerequisites are met:

The data connection protection commands are exchanged between the adapter and the server after you have successfully logged in but before you establish the data connection.

  1. By default, the adapter issues PBSZ 0 command before issuing the PROT command.

  2. The WebSphere Adapter for FTP supports Clear and Private levels of data channel protection.

Refer to the following configuration table that represents the different combinations.

Configuration information

Configuration Protocol FTPS connection mode Data connection encryption Description
1 FTP over SSL Implicit Clear With this configuration, the adapter connects to the FTP server in SSL implicit mode and the data is transferred in the clear text format and there is no data encryption.
2 FTP over SSL Implicit Private With this configuration, the adapter connects to the FTP server in SSL implicit mode and the data channel is encrypted.
3 FTP over SSL Explicit Clear With this configuration, the adapter connects to the FTP server in SSL explicit mode and the data is transferred in the clear text format. There is no data encryption.
4 FTP over SSL Explicit Private With this configuration, the adapter connects to the FTP server in SSL explicit mode and the data channel will be encrypted.
5 FTP over TLS Implicit Clear With this configuration, the adapter connects to the FTP server in TLS implicit mode and the data is transferred in clear text format. There is no data encryption.
6 FTP over TLS Implicit Private With this configuration, the adapter connects to the FTP server in TLS implicit mode and the data channel is encrypted.
7 FTP over TLS Explicit Clear With this configuration, the adapter connects to the FTP server in TLS explicit mode and the data channel is in clear text format. There is no data encryption.
8 FTP over TLS Explicit Private With this configuration, the adapter connects to the FTP server in TLS explicit mode and the data channel is encrypted.

Files passing through the FTP server are vulnerable to third-party interference when SSL is not configured for use with the adapter. Using SSL prohibits data from being modified intentionally or unintentionally during transport and protects it from being intercepted. SSL is effective because it uses several cryptographic processes: public key cryptography for authentication with the FTP server and secret key cryptography and digital signatures for privacy and data integrity. SSL allows the adapter to authenticate the identity of the FTP server.

  1. In the external service wizard, set the Protocol to FTP over SSL - File Transfer Protocol over Secure Socket Layer or FTP over TLS - File Transfer Protocol over Transport Layer Security.

  2. In the Secure configuration area of the external service wizard, set the FTPS connection mode to either Explicit or Implicit mode. The default port number used for Explicit mode is 21 and Implicit mode is 990. Change the port number accordingly if the FTPS server runs on a different port.

  3. Set Data channel protection level to Private or Clear. If you select the:

    • Private level of data protection, the data transfer is integrity and confidentiality protected
    • Clear level of data protection, the data transfer is in clear form.

      The default value is set to private.

  4. Set the adapter trust store. A trust store helps an FTP client decide what it can trust. While using SSL, FTPS server sends its certificate to the FTP client for verification. The FTP client verifies the certificate to ascertain that it is communicating with the intended FTP server. To enable this verification process, the FTP server's certificate must be present in the client's trust store.

    1. Use keytool utility, to import servers certificate into clients trust store. For example, enter the command keytool -import -v -alias serverCert -file server.cert -keystore clientTrustStore where server.cert is the certificate of the server and clientTrustStore is the trust store of the client.

    2. Set Keystore type to the type of keystore used while creating the truststore.

    3. Set Truststore file to the absolute path of the truststore file.

    4. Set Truststore password to the password of the truststore. The password is used to check the integrity of the contents of the truststore.

  5. Optional: Client authentication can be enabled while establishing an SSL connection. When using SSL, FTPS server requests for the clients certificate. The FTPS server verifies the certificate sent by the client to ascertain that it is communicating with the intended client. To enable this verification process, the FTPS server has to support client authentication and the clients certificate must be present at the servers trust store. At the clients end, clients keystore information has to be available for the exchange of the certificate to take place.

    1. You can create a keystore using the keytool utility.

    2. Set the Keystore file to the absolute path of the keystore.

    3. Set the Keystore password to the password of the keystore. The password is used to check the integrity of the contents of the keystore

    4. Set the Key password to the password provided while creating the key in the keystore. This value is required to extract the certificate from the keystore while establishing an SSL connection.

      Ensure the value of Keystore type property is same as the type used while creating the keystore.



Next topic: Configure the adapter for FIPS 140-2


Related concepts:

Support for FTPS protocol


Related reference:

Activation specification properties

Managed (J2C) connection factory properties

Feedback


Configure the adapter for FIPS 140-2

The federal information processing standard 140-2 (FIPS) is a United States government standard for cryptographic features like encryption, decryption, hashing (message digests), secure socket layers, transport layer security, Internet Protocol security, Secure shell, signatures, key exchange, and key or certificate generation used in software products and modules. If you are an user working with the United States government who must conform to the FIPS standard, you can configure the adapter to run in FIPS mode.

Configure the adapter to run in FIPS mode restricts the adapter working with modules whose cryptographic features comply with FIPS approved methods and providers. From an adapter perspective, running in FIPS mode restricts the adapter using the transport layer security (TLS) secure socket protocol. A single JVM cannot be in FIPS mode. It must not contain non-FIPS mode JSSE applications that are executed at the same time.

For the adapter to run in FIPS mode, the FTP server must support SSL v3.1, which is the same as TLS v1.0, and it must be enabled through the wizard of the FTP server. If not properly supported by SSL v3.1, the SSL handshake with the adapter may fail.

When in FIPS 140-2 mode, IBM WebSphere Adapter for FTP uses the FIPS 140-2 approved cryptographic provider(s); IBMJCEFIPS (certificate 376) and IBMJSSEFIPS (certificate 409). The certificates are listed on the NIST website at http://csrc.nist.gov/groups/STM/cmvp/documents/140-1/1401val2011.htm.

To run the adapter in FIPS mode, you must instruct the adapter to use the IBM Java Secure Socket Extension (IBMJSSE2) provider package. The IBMJSSE2 provider is the preregistered Java secure socket extension provider in the Java security file in IBM SDK, version 6.0. IBMJSSE2 uses FIPS-approved packages.

The Secure Socket Layer (SSL) is not supported in FIPS mode.

To run the adapter in FIPS mode:

  1. In the IBMJSSE2 provider, set the com.ibm.jsse2.JSSEFIPS property to True.

    1. Follow the steps to configure the values:

    • Invoke IBM Business Process Manager administrative console by connecting to http://<hostname>:<portnumber/ibm/console/. For example, http://9.186.116.151:9060/ibm/console/

    • Navigate to Servers.

    • Select WebSphere application servers from Server Types.

    • Select Configuration, Server Infrastructure, Java and Process Management, and Process Definition.

    • Select Additional properties, Java Virtual Machine, and Custom properties.

    • Click New and set Name to com.ibm.jsse2.JSSEFIPS.

    • Set Value to true.

  2. Set the following security properties so the IBMJSSE2 provider handles all JSSE requests.

    1. Set the ssl.SocketFactory.provider property to com.ibm.jsse2.SSLSocketFactoryImpl.

    2. Set the ssl.ServerSocketFactory.provider property to com.ibm.jsse2.SSLServerSocketFactoryImpl.
    3. Follow the steps to configure the values:

    • Invoke <jave-home>/lib/security/java.security, where <java-home> is the home path of the BPMs JVM. For example, C:\IBM\WebSphere\ProcServer\java\jre\lib\security\java.security

    • Open the file, java.security, and find the segment similar to the listed one. 
      # Default JSSE socket factories
#ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
#ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
# WebSphere socket factories (in cryptosf.jar)
ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory
    • Uncomment the default JSSE socket factories and comment the WebSphere socket factories. The settings are displayed as follows: 
      # Default JSSE socket factories
ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
# WebSphere socket factories (in cryptosf.jar)
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

  3. In the security properties file, add the IBMJCEFIPS provider com.ibm.crypto.fips.provider.IBMJCEFIPS to the provider list above the IBMJCE provider. Follow the security.provider.n=providername format where n denotes the order of the provider. The provider with a value of 1 is considered before the provider with a value of 2. Do not remove the IBMJCE provider.

    1. Follow the steps to configure the values:

    • Invoke <jave-home>/lib/security/java.security, where <java-home> is the home path of the BPMs JVM. For example, C:\IBM\WebSphere\ProcServer\java\jre\lib\security\java.security

    • Open the file, java.security, and find the segment similar to the listed one. The list displays the providers and their preference orders. 
      #security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS
security.provider.1=com.ibm.crypto.provider.IBMJCE
security.provider.2=com.ibm.jsse.IBMJSSEProvider
security.provider.3=com.ibm.jsse2.IBMJSSEProvider2
security.provider.4=com.ibm.security.jgss.IBMJGSSProvider
security.provider.5=com.ibm.security.cert.IBMCertPath

  4. Edit the java.security file to insert the IBMJCEFIPS provider (com.ibm.crypto.fips.provider.IBMJCEFIPS) before the IBMJCE provider, and also renumber the other providers in the provider list.

    • If the provider exists, uncomment the line, com.ibm.crypto.fips.provider.IBMJCEFIPS and ensure that it is set before the line, com.ibm.crypto.provider.IBMJCE

    • After you made the settings, the file is displayed as follows: 
      security.provider.1=com.ibm.crypto.fips.provider.IBMJCEFIPS
security.provider.2=com.ibm.crypto.provider.IBMJCE
security.provider.3=com.ibm.jsse.IBMJSSEProvider
security.provider.4=com.ibm.jsse2.IBMJSSEProvider2
security.provider.5=com.ibm.security.jgss.IBMJGSSProvider
security.provider.6=com.ibm.security.cert.IBMCertPath


For more details on configuring security details, see the security documentation for BPM or WebSphere Enterprise Service Bus.



Previous topic: Configure the adapter for FTPS protocol

Feedback


Support for SFTP protocol

SFTP, is a protocol that uses Secure shell (SSH) to transfer files. Unlike standard FTP, it encrypts both commands and data, preventing passwords and sensitive information from being transmitted over the network. It is functionally similar to FTP, but because it uses a different protocol, you cannot use a standard FTP client to talk to an SFTP server, or connect to an FTP server with a client that supports only SFTP.

  1. Server verification Server verification is a method where the client verifies the identity of the server before establishing the connection.
  2. Public key authentication Public key authentication is one of the most secure methods used to authenticate when using a Secure Shell. Public key authentication uses a pair of computer generated keys, one public and one private. The public key can be distributed and resides in the SFTP server. The private key is unique to the user and must not be shared.
  3. Configure the adapter for SFTP protocol SFTP (SSH-File Transfer Protocol) is a network protocol that provides a mechanism for file transfer over a reliable data stream. SFTP runs on a secure SSH channel on port 22 and encrypts all traffic using either user name and password authentication or public key authentication. Public key authentication uses a pair of computer generated keys, one public and one private.



Related concepts:

Support for FTPS protocol

Feedback


Server verification

Server verification is a method where the client verifies the identity of the server before establishing the connection.

The adapter performs the server verification when the SFTP protocol is enabled. The adapter checks the SFTP server that it is trying to establish a connection with to see whether it is a trusted server or not.

Server verification requires a host key file as the input. The host key file must be available on the adapter workstation with the host keys of the trusted servers added to it. The entries in the host key file have to adhere to OpenSSH format of the KNOWN_HOSTS file.

The adapter verifies the server by comparing the host key presented by the server with the host keys present in the host key file. The adapter connects to the server only if the host key of the server is available in the host key file. If the host key of a trusted server is different from the one that is present in the host key file, then the host key entry in the host key file has to be modified to reflect the new entry.

While configuring the adapter to work with an SFTP server running on a non-standard port (other than port number 22), the host key must be in the following format in the host key file.

[Hostname]:Portnumber hostkeyentry

The following is an example of host key when a non-standard port is used. 

[9.186.116.151]:2022 ssh-rsa AAAB3NzaC1yc2EAAAABIwAAAIEA2mRkaED9+e2WtJ/
ECkVTpT8Lg9MKutmPqNAXOr7u5SOIjEry984mG4v79f6VkvjYS2PApwHvUSqxWm761CzsgV+8fs/
yDpYfLPXoHskF9Hp5RknWXpIC9BfzM+mov0BA/VCFBr2d77ELEeVANQT5zNfDiOCOnT0BT2MpcvcgYKc=

If the server is not trusted (the host key is not present in the host key file), the adapter does not connect to the server and the connection request fails, indicating that a connection was attempted to a non-trusted server and connection cannot be established due to security reasons.

To provide both the host name and the IP address, specify them, separating them with a comma, in the host key entry.



Next topic: Public key authentication


Related tasks:

Configure the adapter for SFTP protocol

Feedback


Public key authentication

Public key authentication is one of the most secure methods used to authenticate when using a Secure Shell. Public key authentication uses a pair of computer generated keys, one public and one private. The public key can be distributed and resides in the SFTP server. The private key is unique to the user and must not be shared.

The following properties are required to enable public key authentication:

Passphrase is an optional property used to provide extra protection for the private key.

The key-pair can be generated using any third-party service and you can choose any of the standard encryption algorithms. The most commonly used algorithm is RSA; however, other algorithms such as DSA can be used.

The key-pair must be in the OpenSSH format.

For secure communication, certain SFTP servers allow the user to configure multiple modes of authentication for a single user. When use these servers, you can configure the users to authenticate to the SFTP server using both the password and the public-private key, simultaneously.

If both the Password (user name and password authentication) and the Private key (public key authentication) values are specified in the external service wizard, the adapter then tries to authenticate to the server using one or both the authentication modes, depending on the authentication mode specified on the SFTP server. If you have specified to use both the Password and Private key as the authentication mode on the SFTP server, then the adapter can access the server only if both the values are valid.



Previous topic: Server verification


Next topic: Configure the adapter for SFTP protocol


Related tasks:

Configure the adapter for SFTP protocol

Feedback


Configure the adapter for SFTP protocol

SFTP (SSH-File Transfer Protocol) is a network protocol that provides a mechanism for file transfer over a reliable data stream. SFTP runs on a secure SSH channel on port 22 and encrypts all traffic using either user name and password authentication or public key authentication. Public key authentication uses a pair of computer generated keys, one public and one private.

Configure WebSphere Adapter for FTP to work with an SFTP server:

  1. Install and configure your SFTP server. There are various SFTP servers to choose from. Install and configure your selected server using the provider-specific installation information.
  2. See either Outbound or Inbound Set deployment and runtime properties to select Protocol as SFTP - Secure shell (SSH) File Transfer Protocol and specify the SFTP server connection and security information in the external service wizard.

You have configured the adapter for SFTP.



Previous topic: Public key authentication


Related concepts:

Public key authentication

Server verification


Related reference:

Activation specification properties

Managed (J2C) connection factory properties

Feedback


Support for confidential logging and tracing

You can configure the adapter to prevent sensitive or confidential data, in the log and trace files, from being viewed by users without authorization.

Log and trace files for the adapter can contain data from your FTP server, which might contain sensitive or confidential information. Individuals without authorization need to view the sensitive customer data, for example, a support specialist must use the log and trace files to troubleshoot a problem.

To protect the data in such situations, the adapter provides the HideConfidentialTrace property. The HideConfidentialTrace property specifies whether you want to prevent confidential user data from displaying in the adapter log and trace files. When this property is enabled, the adapter replaces the confidential data with XXX.

The following types of information are considered potentially sensitive data and are hidden:

The following types of information are not considered user data and are not hidden:


Feedback


User authentication

The adapter supports several methods for supplying the user name and password needed to connect to the FTP server. By understanding the features and limitations of each method, you can pick a method that provides the appropriate level of security and convenience for your application.

To integrate an adapter into your application, you must provide the user name and password for the adapter to use at run time on IBM Business Process Manager or WebSphere Enterprise Service Bus to connect to FTP server to process outbound requests and inbound events.

At run time, the adapter needs to provide the user name and password to connect to the FTP server. To connect without user intervention, the adapter must access a saved copy of the user information. In a server environment, there are several methods for saving user information. You can configure the adapter to get your user information, through any of the following methods:

Saving the user name and password in adapter properties is a direct way to provide this information at run time. You provide this user name and password when use the external service wizard to configure your module. Although directly specifying the user name and password seems the most straightforward method, it has important limitations. Adapter properties are not encrypted; the password is stored as clear text in fields that are accessible to others on the server. Also, when the password changes, update the password in all instances of the adapter that access that FTP server. This includes the adapters embedded in application EAR files and adapters that are separately installed on the server.

Use a data source allows you to use a connection already established for another application. For example, if multiple applications access the same database with the same user name and password, the applications can be deployed using the same data source. The user name and password can be known only to the first person who deploys an application to that data source or who defines a data source separately.

Use a J2C authentication data entry, or authentication alias, created with the Javaâ„¢ Authentication and Authorization Service (JAAS) feature of Java EE security is a robust, secure way to deploy applications. An administrator creates the authentication alias used by one or more applications that need to access a system. The user name and password must be known only to that administrator, who can change the password in a single place, when a change is required.

For secure communication, certain SFTP servers allow the user to configure multiple modes of authentication for a single user. When use these servers, you can configure the users to authenticate to the SFTP server using both the password and the public-private key, simultaneously.

If both the Password (user name and password authentication) and the Private key (public key authentication) values are specified in the external service wizard, the adapter then tries to authenticate to the server using one or both the authentication modes, depending on the authentication mode specified on the SFTP server. If you have specified to use both the Password and Private key as the authentication mode on the SFTP server, then the adapter can access the server only if both the values are valid.



Related tasks:

Create an authentication alias

Feedback


Deployment options

There are two ways to deploy the adapter. You can either embed it as part of the deployed application, or you can deploy it as a stand-alone RAR file. The requirements of the environment affect the type of deployment option you choose.

The following are the deployment options:

An embedded adapter is bundled within an enterprise archive (EAR) file and is available only to the application with which it is packaged and deployed.

A stand-alone adapter is represented by a stand-alone resource adapter archive (RAR) file, and when deployed, it is available to all deployed applications in the server instance.

While creating the project for your application using IBM Integration Designer, you can choose how to package the adapter [either bundled with the (EAR) file or as a stand-alone (RAR) file]. Your choice affects how the adapter is used in the run time environment and how the properties for the adapter are displayed on the administrative console.

Choosing either to embed an adapter with your application or to deploy the adapter as a stand-alone module depends on how you want to administer the adapter. For a single copy of the adapter and do not care about disruption to multiple applications when you upgrade the adapter, then you would be more likely to deploy the adapter as a stand-alone module.

If you plan to run multiple versions, and if you care more about potential disruption when you upgrade the adapter, you would be more likely to embed the adapter with the application. Embedding the adapter with the application allows you to associate an adapter version with an application version and administer it as a single module.


Considerations for embedding an adapter in the application

Consider the following items if you plan to embed the adapter with your application:


Considerations for using a stand-alone adapter

Consider the following items if you plan to use a stand-alone adapter:


Considerations while deploying adapters with different versions

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for FTP version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for FTP" as IBM WebSphere Adapter for FTP loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3.

There are occasions when you work with embedded adapters that do not need a client-server communication, stand-alone adapters that need a server connection, or a hybrid mix of adapter connections.

The following scenarios cover the different behaviors of AFC version conflict detection, when you are deploying two or more adapters and at least one of the adapter version is 7.5 or higher.

Deploy a stand-alone Adapter

  1. Install WebSphere Adapter for Flat Files version 7.0.1.0 through the BPM administrative console.
  2. Install WebSphere Adapter for SAP Software version 7.5.0.0 through the administrative console.

  3. Create ActivationSpec for an ALE pass-through inbound operation.

  4. Create an application in IBM Integration Designer for a stand-alone ALE pass-through inbound operation.
  5. Install and start the application through the administrative console.

  6. Verify the error.

An error message is generated in the log/trace area of IBM Business Process Manager, to indicate an AFC version conflict. Deploy an embedded Adapter

  1. Import a build of WebSphere Adapter for FTP version 7.0.1.0, using a RAR file.

  2. Create a FTP Inbound EMD operation.
  3. Import a build of WebSphere Adapter for Oracle E-Business Suite version 7.5.0.0, using a RAR file.

  4. Create an Oracle inbound EMD operation, in the same module where you have created the FTP Inbound EMD operation.
  5. Deploy the module to IBM Business Process Manager.
  6. Check the trace.

At step 5, the deployment fails. At step 6, you get an internal error message due to the AFC version conflict.

To avoid a name conflict between the business object generated by the two adapters, generate the artifacts into different folders.

Deploy a combination of stand-alone and embedded Adapters

  1. Install WebSphere Adapter for JDBC version 7.0.1.0 through theIBM Business Process Manager administrative console.

  2. Create an ActivationSpec for a JDBC inbound operation.

  3. Create an application in IBM Integration Designer for a JDBC inbound operation, for the stand-alone Adapter deployment.
  4. Deploy the JDBC inbound application and trigger your inbound events.

  5. Create an application in IBM Integration Designer for a WebSphere Adapter for SAP Software version 7.5.0.0 inbound embedded Adapter deployment.
  6. Deploy an SAP inbound application, and trigger your inbound events.

You can resolve the AFC version conflict by using different class loaders for the stand-alone and embedded deployments. With this approach, the migration process handles different CWYBS_AdapterFoundation.jar files and do not conflict with each other. You can start both JDBC and SAP inbound applications successfully, and process Inbound events without exception.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


Feedback


WebSphere Adapters in clustered environments

You can improve adapter performance and availability by deploying a module on a clustered server environment. Clusters are groups of servers that are managed together to balance workloads and to provide high availability and scalability.

The module you deployed is replicated across all servers in a cluster, regardless of whether you deploy the module using a stand-alone or an embedded adapter. The following IBM products support WebSphere Adapters in a clustered environment:

To deploy and configure WebSphere Adapter for FTP in a clustered environment, see: Deploy the module in a clustered environment. When you set up a server cluster, you create a Deployment Manager profile. The HAManager, a subcomponent of the Deployment Manager, notifies the Javaâ„¢ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container to activate an adapter instance. For information about creating clustered environments, see the following link: http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5mx/index.jsp?topic=/com.ibm.wbpm.imuc.z.doc/topics/tins_zos_create_cluster.html.

Use WebSphere Extended Deployment, you can optionally enhance the performance of adapter instances in your clustered environment. WebSphere Extended Deployment extends the WAS ND capabilities by using a dynamic Workload Manager instance instead of a static Workload Manager. The dynamic Workload Manager instance can optimize the performance of adapter instances in the cluster by dynamically balancing the load of the requests. It means that application server instances can be automatically stopped and started based on the load variations, allowing systems with different capacities and configurations to handle load variations evenly. For information about the benefits of WebSphere Extended Deployment, see http://publib.boulder.ibm.com/infocenter/wxdinfo/v6r1m1/index.jsp.

In clustered environments, adapter instances can handle both inbound and outbound processes.

Restriction: During inbound communication WebSphere Adapter for FTP is not able to switch polling between a IBM Business Process Manager or WebSphere Enterprise Service Bus cluster backup node and the cluster's primary node when each node is installed on a different operating system. For example, if the adapter starts polling on a primary Windows node, it cannot switch to a backup UNIX node because it cannot process the Windows path used for the directory storing in progress events.


High availability for inbound processes

Inbound processes are based on events triggered as a result of updates to data in the FTP server. WebSphere Adapter for FTP is configured to detect updates by polling an event table. The adapter then publishes the event to its endpoint.

In a clustered environment, the event directory must be on a shared file system and not local to any of the cluster machines.

When you deploy a module to a cluster, the Java Platform, Enterprise Edition (JEE) Connector Architecture (JCA) container checks the enableHASupport resource adapter property. If the value for the enableHASupport property is true, which is the default setting, all of the adapter instances are registered with the HAManager with a policy 1 of N. This policy means that only one of the adapter instances starts polling for events. Although other adapter instances in the cluster are started, they remain dormant with respect to the active event until the active adapter instance finishes processing the event. If the server on which the polling thread was started shuts down for some reason, an adapter instance running on one of the backup servers is activated.

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events/messages even if the enableHASupport property is set to True. This is because the alwaysactivateAllMDBs property in the JMS activation specification is set to True. To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. See Disable end point applications of the passive adapter .

If the value for the enableHASupport property is set to False, all adapter instances poll for events in the inbound cluster and the adapter works in an Active-Active configuration. Multiple instances of WebSphere Adapter for FTP can be made active in a HA cluster in the active configuration mode. When more than one adapter instance actively polls in a cluster setup, it serves as a load balancer. If one of the adapter instances in the cluster fails, the other active instances in the cluster handle the events.

In clustered environments, when the adapter works in a HA Active-Active configuration, it provides both high availability and load balancing support. This functionality is useful in production environments where high performance is needed.

In the HA Active-Active configuration, WebSphere Adapter for FTP ensures that an event is not processed by more than one adapter instance. This results in each adapter instance polling for a unique event, and delivering the event without any duplication to the endpoint.

Database support in clustered environments

The adapter currently supports only the following databases:

If a different database is used, you must manually create the event persistence table and the file table. For more information about the event table and the file table, see Event store structure and File store structure .

In addition, the databases must support the following features to enable the adapter to run in the Active-Active configuration:


High availability for outbound processes

In clustered environments, multiple adapter instances are available to perform outbound process requests. So, if the environment has multiple applications that interact with WebSphere Adapter for FTP for outbound requests, then you might improve performance by deploying the module to a clustered environment. In a clustered environment, multiple outbound requests can be processed simultaneously, so they are not attempting to process the same record.

If multiple outbound requests are attempting to process the same record, such as a Customer address, the workload management capability in WAS Network Deployment distributes the requests among the available adapter instances in the sequence they were received. As a result, these types of outbound requests in a clustered environment are processed in the same manner as in a single server environment: one adapter instance processes only one outbound request at a time. For more information about workload management, see the following link: http://publib.boulder.ibm.com/infocenter/wasinfo/v8r0/index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/trun_wlm.html.


Feedback


Adapter customization with Custom Parser Class

The WebSphere Adapter for FTP uses Apache Commons Net API v2.0 to connect to the FTP server. The adapter works with the servers that provide standard listing format such as most UNIX or Linux built-in servers do. If the FTP server ls -l output is different from the standard format, use the CustomParserClassname property and set an appropriate class name to parse the output. The CustomParserClassName property, which is in the activation specification and in the managed connection factory, must contain the complete path of the class.

Commons Net API provides an interface, org.apache.commons.net.ftp.FTPFileEntryParser, that you can implement to parse the long list (ls -l) output. By using the class that implements this interface, the adapter can work with FTP servers that do not provide standard listing. The adapter provides a basic implementation of this interface. The class name is com.ibm.j2ca.ftp.util.FTPLongListEntryParser.

The following methods are in the Javaâ„¢ interface: 

package org.apache.commons.net.ftp;
public interface FTPFileEntryParser{
FTPFile parseFTPEntry(String listEntry);
String readNextEntry(BufferedReader reader) throws IOException;
List preparse(List original);}

For more information about each of the methods in the Apache Commons Net API v2.0 documentation, see http://commons.apache.org/net/

If the FTP server generates MS-DOS type listing (such as the format returned by Windows built-in Internet Information Services (IIS) FTP server configured in MS-DOS directory listing style), you need to implement a class based on org.commons.apache.net.ftp.parser.NTFTPEntryParser. The NTFTPEntryParser is provided by Apache Commons Net API.

For any other format of the directory listing, implement the appropriate parser class and provide the class name in the Custom Parser Class Name property.


Feedback


Migrate to version 7.5.0.3 of WebSphere Adapter for FTP

By migrating to version 7.5.0.3 of WebSphere Adapter for FTP, you automatically upgrade from the previous version of the adapter. Additionally, you can migrate applications that embed an earlier version of the adapter, so the applications can use features and capabilities present in version 7.5.0.3.


Feedback


Migration considerations

WebSphere Adapter for FTP version 7.5.0.3 may have some features and updates that might affect your existing adapter applications. Before migrating applications that use WebSphere Adapter for FTP, you must consider some factors that might affect your existing applications.


Compatibility with earlier versions

WebSphere Adapter for FTP version 7.5.0.3 is fully compatible with the custom business objects (XSD files) and data bindings that are created using the adapter version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 and enables the existing business objects and data bindings to work well in the latest version of the adapter.

Because version 7.5.0.3 of WebSphere Adapter for FTP is fully compatible with version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2, any of applications that used previous versions of WebSphere Adapter for FTP run unchanged when you upgrade to version 7.5.0.3. However, if you want applications to use features and functionality present in version 7.5.0.3 of the adapter, perform the migration of the artifacts as well as the upgrade of the adapter.

The migration wizard replaces (upgrades) version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 of the adapter with version 7.5.0.3 and enables version 7.5.0.3 features and functionality for use with applications.

The migration wizard does not create components or modify existing components, such as mappers and mediators to work with version 7.5.0.3 of the adapters. If any of applications embed an adapter that is version 7.5.0.2 or earlier and you are upgrading to version 7.5.0.3, and you want applications to take advantage of the features and functions in version 7.5.0.3, you might need to change those applications.

If the artifacts within a module have inconsistent versions, the entire module is marked as unavailable for migration and cannot be selected. Version inconsistencies are recorded in the workspace log, as they indicate that a project might be corrupted.

The adapter migration wizard in IBM Integration Designer Version 7.5.1 only supports the migration of adapters from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, and version 7.5.0.2 to version 7.5.0.3. It does not support the adapter migration from lower versions to any of the versions before version 7.5.0.3.


Decide whether to upgrade or to upgrade and migrate

The default processing of the migration wizard is to perform an upgrade of the adapter and to migrate the application artifacts so the applications can use features and functions in version 7.5.0.3 of the adapter. When you choose to upgrade the adapter by selecting a project, the wizard automatically selects the associated artifacts for migration.

If you decide to upgrade the adapter from version 6.1.x, version 6.2.x, version 7.0.x, version 7.5.0, or version 7.5.0.2 to version 7.5.0.3, but you do not want to migrate the adapter artifacts, you can do so by clearing the adapter artifacts from the appropriate area of the migration wizard.

Run the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.


Migrate multiple adapters referred within a project

When a module contains one or more connector projects, each of which references to different adapters ( a module project that contains connector projects referring to JDBC and SAP adapters), the migration wizard identifies the artifacts belonging to each adapter and migrates these artifacts without disrupting the artifacts of other adapters.

When you select the module project and launch the migration wizard:

If you select the connector project and launch the migration wizard:


Run the migration wizard in a test environment

Because adapter migration might require you to change those applications that use version 7.5.0.3 of WebSphere Adapter for FTP, always perform the migration in a development environment first and test applications before deploying the application to a production environment.

The migration wizard is fully integrated with the development environment.


Deprecated features

A deprecated feature is one that is supported but no longer recommended and that might become obsolete. The following features from earlier versions of WebSphere Adapter for FTP have been deprecated in version 6.2.x and might require changes to applications:



Related tasks:

Performing the migration

Upgrading but not migrating a project

Feedback


Performing the migration

You can migrate a project or EAR file to version 7.5.0.3 using the adapter migration wizard. When the tool is finished, the migration is complete and you can work in the project or deploy the module.

Review the information in Migration considerations. To perform the migration in IBM Integration Designer.

After migration is complete, the following changes occur:

The following steps describe how to run the adapter migration wizard from the connector project menu while in the Javaâ„¢ EE perspective in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.

    Ensure that you do not modify the contents of the RAR or copy the adapter JAR file outside the connector project.

  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Java EE perspective.
  4. Right-click the module and select Migrate connector project. For example, the adapter RAR module.

    You can also launch the adapter migration wizard in the following ways:

    • Right-click the project in the Java EE perspective and select Migrate adapter artifacts.

    • From the Problems view, right-click a migration-specific message and select Quick Fix to correct the problem.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. If you are migrating a module project, this field lists all the connector projects in the module project. Select the source project from the list. See Migrate multiple adapters referred within a project.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector you want to migrate.
    3. The Target version field displays the version corresponding to the target connector that you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated. If you are migrating a module project, this area lists only the selected module project. If you are migrating a connector project within the module project, this area lists all projects which reference the selected connector project, including the module project. By default, all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated. You can migrate any project that you have not selected at a later time. Previously migrated projects, projects with a current version, and projects that contain errors are unavailable for migration and are not selected. See Upgrading but not migrating a project.

    5. Click Next. A warning window is displayed with the message, “Properties that are not supported in this version of the target adapter will be removed during the migration”.

    6. Click OK.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before running the migration process, the wizard performs a backup of all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

    Upon completing the migration successfully, all backed up projects are deleted.

  8. If you are migrating an EAR file, optionally create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For more information about exporting and deploying an EAR file, sees devoted to it in this documentation.

    If the adapter module created on version 6.2 uses the FTPS protocol, you need to manually specify the truststore path and truststore password values in the BPM administrative console, after the migration is complete. These values are required to perform server authentication while establishing a connection to SSL.

    Use the key tool utility to import the FTPS server's certificate into the adapter's trust store. For example, enter the command, keytool -import -v -alias serverCert -file server.cert -keystore clientTrustStore, where server.cert is the FTPS server's certificate and clientTrustStore is the trust store of the adapter.

    Set the trust store by updating the JVM property through IBM Business Process Manager administrative console. For example, javax.net.ssl.trustStore=C:\MyKeyStore\clientTrustStore, where clientTrustStore is the truststore of the adapter.

    Set the trust store password by updating the JVM property through IBM Business Process Manager administrative console. For example, javax.net.ssl.trustStorePassword=truststorepassword

The project or EAR file is migrated to version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.


After completing the migration, you must manually update the structure of the event table. To update the structure of the event table, use the sample database scripts available at "<IID_HOME>\Resource Adapters\FTP_7.5.0.2\Scripts".



Related tasks:

Upgrading but not migrating a project


Related reference:

Migration considerations

Feedback


Migrate databases

With WebSphere Adapter for FTP, version 7.5, the schema of the event persistence table is modified. Hence, after completing the adapter migration, update the structure of the event table to work with the adapter version 7.5. Use the sample database scripts available at "<IID_HOME>\Resource Adapters\FTP_7.5.0.2\Scripts" to update the structure of the event table.

Before updating the structure of the event table, ensure that only the failed events are available in the event table. Ensure that you process or delete the unprocessed events before performing this task.

The database migration is required for both single and HA Active-Active instance of adapter configuration. After migrating the adapter, if you use an existing event table with the adapter version 7.5, then a runtime exception is thrown.

Perform the following steps to run the scripts and update the structure of the event table.

  1. Go to the "<IID_HOME>/Resource Adapters/FTP_7.5.0.2/Scripts" folder.
  2. Double-click one of the following scripts corresponding to the database:

    • scripts_db2_upgrade.sql – for DB2 and Derby database
    • scripts_mssql_upgrade.sql – for Microsoft SQL Server database
    • scripts_oracle_upgrade.sql – for Oracle database

  3. The selected script performs the following actions:

    1. A temporary event table with the same structure of the existing event table is created.

      Ensure the name of the temporary event table (mentioned in the script) is not already in use for any existing table. If the name is already in use, then change the name of the temporary event table in the database script accordingly.

    2. The event data from the existing event table is copied to the temporary event table.

    3. If the default name of the event table (FTPTABLE) is not used in your application or project, ensure specified the name of the existing event table in the database script.
    4. An event table with the new structure is created.

    5. After the data from the temporary table is copied to the new event table, the temporary table is deleted from the database.

The updated event table can now be used in your project.


Feedback


Upgrading but not migrating a project

You can upgrade the adapter from an earlier version, to version 7.5.0.3 while choosing not to migrate the adapter project artifacts. Running the migration wizard without selecting any adapter artifacts installs and upgrades your adapter. As the artifacts are not migrated, applications cannot take advantage of the features and capabilities that exist in version 7.5.0.3 of the adapter.

  1. Import the PI (project interchange) file into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.

  3. In the Javaâ„¢ EE perspective, right-click the project name and click Migrate connector project. The Adapter Migration wizard is displayed.

  4. In the Select Projects window, clear the dependent artifact projects, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter will be removed during the migration.”

  5. Click OK.

  6. In the Review Changes window, review the migration changes that occur during updating the project. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    When v6.x FTP adapter module configured for FTPS protocol, the truststore of the adapter will be configured in NodeDefaultTrustStore in the Security -> SSL Certificates and Key Management -> Key stores and certificates section of Administrative console of the BPM.

    While using v6.x module with FTPS protocol configured, and the adapter is upgraded to version 7.0, the truststore properties needs to be configured in the 'Managed Connection Factory properties' or 'Activation Specification properties'.

    If you prefer to configure the truststore at the administrative console of the BPM, the following additional steps need to be performed after configuring the truststore in NodeDefaultTrustStore of the BPM administrative console.

    1. Go to <java-home>/lib/security/java.security where <java-home> is the directory in which the Java file of the BPM is installed. For example, C:\IBM\WebSphere\ProcServer\java\jre\lib\security\java.security

    2. Open the file and find the segment similar as below: 
      # Default JSSE socket factories
#ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
#ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
# WebSphere socket factories (in cryptosf.jar)
ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory
    3. Uncomment the default JSSE socket factories and comment the WebSphere socket factories. The segment is displayed as shown here after this setting: 
      # Default JSSE socket factories
ssl.SocketFactory.provider=com.ibm.jsse2.SSLSocketFactoryImpl
ssl.ServerSocketFactory.provider=com.ibm.jsse2.SSLServerSocketFactoryImpl
# WebSphere socket factories (in cryptosf.jar)
#ssl.SocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLSocketFactory
#ssl.ServerSocketFactory.provider=com.ibm.websphere.ssl.protocol.SSLServerSocketFactory

    4. Restart the BPM.

The project can now be used with WebSphere Adapter for FTP, version 7.5.0.3.



Related tasks:

Performing the migration

Export the module as an EAR file

Install the EAR file


Related reference:

Migration considerations

Feedback


Migrate WebSphere Business Integration applications

You need to migrate the WebSphere Business Integration applications so they become compatible with Version 7.5.0.3 of your adapter.

Migrate WebSphere Business Integration applications for use with Version 7.5.0.3 of your WebSphere adapter is a multistep process. First, the artifacts from WebSphere InterChange Server are migrated and converted. A project is then created for the artifacts in IBM Integration Designer. In the remaining steps, the adapter-specific artifacts are migrated and converted into the JCA-compliant format supported by Version 7.5.0.3 of the adapter.


Example

The following diagram shows the wizards that you use to migrate WebSphere Business Integration solutions from WebSphere InterChange Server, so these applications can be used with Version 7.5.0.3 of your adapter.


Feedback


Migrate applications from WebSphere InterChange Server

To use Version 7.5.0.3 of WebSphere Adapter for FTP with applications from WebSphere InterChange Server, you need to migrate the application artifacts and convert them so they can be deployed and run on IBM Business Process Manager or WebSphere Enterprise Service Bus. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

The following figure illustrates the flow of the migration task. The steps that follow the figure describe this task at a high level only. See the topics following this roadmap for the details on how to perform each of these steps.

Figure 1. Roadmap for migrating applications from WebSphere InterChange Server

Migrate applications from WebSphere InterChange Server

This task consists of the following steps:

  1. Run the WebSphere InterChange Server migration wizard.

    The WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer. The migrated adapter artifacts are not fully JCA-compliant at the completion of this task.

  2. Verify the WebSphere InterChange Server migration is successful.

    Review all messages from the Migration results window and take action if required.

  3. Consider the implications of using Version 7.5.0.3 of WebSphere Adapter for FTP.

    In addition to considerations for migrating WebSphere InterChange Server applications, you need to consider how Version 7.5.0.3 of WebSphere Adapter for FTP works with the migrated applications. Some of the adapter operations supported by WebSphere InterChange Server applications might be supported and implemented differently with Version 7.5.0.3 of the adapter.

  4. Run the adapter migration wizard.

    Run the adapter migration wizard to update adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl files) for use with Version 7.5.0.3 of the adapter.


Feedback


Migration considerations for WebSphere Business Integration adapters

By migrating to WebSphere Adapter for FTP Version 7.5.0.3, you have an adapter that is compliant with the Javaâ„¢ Platform, Enterprise Edition (JEE) Connector Architecture (JCA) and designed specifically for service-oriented architecture.


Application artifacts

Before running the adapter migration wizard, use the WebSphere InterChange Server migration wizard to generate the application artifacts for the WebSphere Business Integration adapter, including the business objects, maps, and collaborations. Then you can run the adapter migration wizard to update the adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) so they are suitably converted into a format that is compliant with JCA.


Run the migration wizard in a test environment first

Because migrating from a WebSphere Business Integration adapter to WebSphere Adapter for FTP might require changes to the applications that use Version 7.5.0.3 of WebSphere Adapter for FTP, always perform the migration in a development environment first and test applications before deploying the application to a production environment.


Feedback


Migrate application artifacts from WebSphere InterChange Server

To migrate the application artifacts into IBM Integration Designer, run the WebSphere InterChange Server migration wizard. The wizard imports and converts most of the artifacts into a format that is compatible with BPM or WebSphere Enterprise Service Bus.

Launch the WebSphere InterChange Server migration wizard from within IBM Integration Designer to migrate the application artifacts from WebSphere InterChange Server format into artifacts that are compatible with BPM or WebSphere Enterprise Service Bus.

For information about how to prepare to migrate artifacts from WebSphere InterChange Server and for detailed instructions on performing the migration and verifying the migration was successful, see http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/index.jsp?topic=/com.ibm.wbpm.wid.imuc.doc/topics/twics.html. Running WebSphere InterChange Server migration wizard might not fully convert adapter-specific artifacts (such as service descriptors, service definitions, and business objects) into IBM Business Process Manager or WebSphere Enterprise Service Bus compatible artifacts. To complete the migration of adapter-specific artifacts, run the adapter migration wizard after you have successfully run the WebSphere InterChange Server migration wizard.

While you run the WebSphere InterChange Server migration wizard, ensure set each connector in the repository to the same adapter version.

The project and application artifacts are migrated and converted into IBM Business Process Manager compatible artifacts.


Run the adapter migration wizard to migrate the adapter-specific artifacts.


Feedback


Migrate adapter-specific artifacts

After a project is created for the artifacts in IBM Integration Designer, you can migrate the project using the adapter migration wizard. The adapter migration wizard updates adapter-specific artifacts such as the schemas and service definition files (.import, .export, and .wsdl) for use with version 7.5.0.3 of the adapter. When you finish running the adapter migration wizard, the migration is complete and you can work in the project or deploy the module.

Before running the adapter migration wizard, do the following steps:

After migration is complete, the module will work only with Version 7.5.0.3 of your adapter.

To perform the migration in IBM Integration Designer.

  1. Import the PI (project interchange) file for an existing project into the workspace.
  2. When projects are created in an earlier version of IBM Integration Designer, the Workspace Migration wizard starts automatically and selects the projects to migrate. Follow the wizard and complete the workspace migration. See http://pic.dhe.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.wid.imuc.doc/topics/tmigsrcart.html.
  3. Change to the Javaâ„¢ EE perspective.
  4. Right-click the connector project and select Migrate connector project.

    You can also launch the adapter migration wizard by using the right-click option and selecting the module project in the Java EE perspective and selecting Migrate adapter artifacts.

    If the adapter type ( CICS/IMS adapter) is not supported by the migration wizard, the Migrate connector project and Migrate adapter artifacts menus are not available for selection. If the adapter project is of the latest version and the module projects referencing this adapter project are also of the latest version, these menus are disabled. When you launch the migration wizard from the connector project while in the Java EE perspective, by default all the dependent artifact projects are selected. If you do not select a dependent artifact project, that project is not migrated.

  5. In the Select Projects window.

    1. The Source connector field displays the name of the connector project that you are migrating. Select the source project from the list.
    2. The Target connector field displays the name of the connector to which you are migrating. If you are working with more than one adapter version, this list displays the names of all the compatible connectors. Select the connector to which you want to migrate.
    3. The Target version field displays the version corresponding to the target connector you selected in the previous step.
    4. The Dependent artifacts project area lists the adapter artifacts that are migrated.
    5. Review the tasks and warnings presented on the welcome page, and click Next. A warning window is displayed with the message, “The properties that are not supported in the version of the target adapter are removed during the migration.”

    6. Click OK.
    7. The migration wizard displays the following message.

    8. click OK to continue with the migration.

  6. In the Review Changes window, review the migration changes that occur in each of the artifacts that you are migrating. To view the details, expand each node by clicking the + sign.
  7. To complete the migration:

    • Click Finish.

    • If the files that need to be updated during migration are in read-only mode, you will be unable to click on the Finish button. To view these files, click Next. The Update Read-only files window displays the read-only files. To update these files and continue with the migration, click Finish. To exit the wizard without migrating the adapter, click Cancel.

    Before performing the migration process, the wizard backs up all projects affected by the migration. The projects are backed up to a temporary folder within the workspace. If the migration fails for any reason, or if you decide to cancel the migration before it completes, the wizard deletes the modified projects and replaces them with the projects stored in the temporary folder.

  8. Select Project > Clean, to refresh and rebuild the workspace for the changes to take effect.

  9. If you are migrating an EAR file, create a new EAR file with the migrated adapter and artifacts, and deploy it to IBM Business Process Manager or WebSphere Enterprise Service Bus. For information about exporting and deploying an EAR file, see Deploy the module for production.

The project is migrated to Version 7.5.0.3. You do not need to run the external service wizard after exiting the adapter migration wizard.


Feedback


Changes to the import, export, and WSDL files after migration

When the WebSphere InterChange Server migration wizard moves the application artifacts into IBM Integration Designer, changes made are reflected in the service definition files: the import, export, and WSDL files.

The migrated adapter artifacts are not fully JCA-compliant at the completion of this task. You can complete the migration of the adapter-specific artifacts (such as service descriptors, service definitions, and business objects) to a JCA compatible format by running the adapter migration wizard.


Changes to the import file

During migration, the affected module artifacts are migrated to an import file. The existing JMS Binding property is changed to the EIS Binding property in the import file. The other property details added in the import file include information about the data binding configuration, changes to the connection information in the Managed Connection Factory properties, and several new method bindings.

The OutputLog property in WebSphere Business Integration Adapter for JText has the default value Output.log. However, its equivalent property FileSequenceLog in WebSphere Adapter for FTP requires a value that includes the absolute path. For example, C:\Output.log. Hence, after migrating the adapter, you must manually edit the import file for outbound and specify the absolute path for the FileSequenceLog property.


Changes to the export file

During migration, the affected module artifacts are migrated to an export file. The existing JMS Binding property is changed to the EIS Binding property in the export file. The other property details added in the export file include information about the data binding configuration, changes to the connection information in the Activation Specification properties, and several new method bindings.


Changes to the WSDL file after migration

During migration, the affected module artifacts are migrated to corresponding WSDL files that include adapter specific service description WSDL artifacts. The service description files become JCA compatible. The WSDL files have an input and output type for each operation. Both the inbound and outbound operations work on their specific input types to produce corresponding output types after the operations are performed.


Feedback


Samples and tutorials

To help you use WebSphere Adapters, samples and tutorials are available from the Business Process Management Samples and Tutorials website.

You can access the samples and tutorials in either of the following ways:


Feedback


Configure the module for deployment

To configure the adapter so that it can be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use IBM Integration Designer to create a module, which is exported as an EAR file when you deploy the adapter. You then specify the business objects you want to build and the system on which you want to build them.



Previous topic: Plan for adapter implementation


Next topic: Deploy the module for production

Feedback


Road map for configuring the module

Before you use WebSphere Adapter for FTP in a runtime environment, configure the module. Understanding this task at a high level helps you perform the steps needed to accomplish the task.

You configure the module for WebSphere Adapter for FTP by using IBM Integration Designer. The following figure illustrates the flow of the configuration task, and the steps that follow the figure describe this task at a high level only. For the details about how to perform each of these steps, sees following this road map.

Figure 1. Road map for configuring the module

Configure the module

This task consists of the following steps, which are described at a high level.

These steps assume that you are using user-defined business objects that require data transformation. If using generic business objects, which do not require data transformation, some of the following steps are ignored. For example, you need not select a data binding and a data handler.

  1. Create an authentication alias to access the FTP server. Perform this step using the administrative console on the server.

  2. Create a module in IBM Integration Designer. You create business objects in the module.
  3. Define the business objects that will be used by the project.

  4. Use the Adapter patterns wizard to create simple services. See Create a simple service with the adapter pattern wizard.

  5. Create a project, which is used to organize the files associated with the adapter using the external service wizard in IBM Integration Designer.
  6. Build business services by running the external service wizard from IBM Integration Designer, and then perform the following steps:

    1. Set the following deployment and runtime properties:

      • Connection properties
      • Security properties
      • Deployment options
      • Function selector - Inbound only

    2. Select a data type and name the operation associated with this data type. For each operation, specify the following:

      • The operation kind. For example, Create, Append, and Exists.

      • Specify if the operation is pass through or user defined.

    3. Select the data binding. Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file.

    4. Select the data handler that performs the conversions between a business object and a native format.

    5. Specify interaction specification property values and generate artifacts. The output from running the external service wizard is saved to a business integration module, which contains the business object or objects, and the import or export file.

If you are performing the step 4, do not follow the other steps following it and exit. If you are not performing the step 4, continue to follow the steps from 5 immediately after the step 3.



Related tasks:

Configure the module for deployment

Deploy the module for production

Feedback


Create an authentication alias

An authentication alias is a feature that encrypts the password used by the adapter to access the FTP server. The adapter can use it to connect to the FTP server instead of using a user ID and a password stored in an adapter property.

To create an authentication alias, you must have access to the administrative console of IBM Business Process Manager or WebSphere Enterprise Service Bus. You must also know the user name and password to use to connect to the FTP server.

The following procedure shows you how to gain access to the administrative console through IBM Integration Designer. If you are using the administrative console directly (without going through IBM Integration Designer), log in to the administrative console and skip to step 2.

Use an authentication alias eliminates the need to store the password in clear text in an adapter configuration property, where it might be visible to others.

To create an authentication alias, use the following procedure.

  1. Start the administrative console.

    To start the administrative console through IBM Integration Designer.

    1. In the Business Integration perspective of IBM Integration Designer, click the Servers tab.

    2. If the server does not show the status as Started, right-click the name of the server ( IBM Business Process Manager) and click Start.
    3. Right-click the name of the server and click Run administrative console.
    4. Log on to the administrative console. If your administrative console requires a user ID and a password, type the ID and password and click Log in. If the user ID and password are not required, click Log in.

  2. In the administrative console, click Security > Secure administration, applications, and infrastructure.

  3. Under Authentication, click Java Authentication and Authorization Service > J2C authentication data.

  4. Create an authentication alias.

    1. In the list of J2C authentication aliases that is displayed, click New.

    2. Click the Configuration tab, and then type the name of the authentication alias in the Alias field.

    3. User ID and password required to establish a connection to the FTP server.

    4. Optional: Type a description of the alias.

    5. Click OK.

      The newly created alias is displayed.

      The full name of the alias contains the node name and the authentication alias name you specified. For example, if you create an alias on the node widNode with the name ProductionServerAlias, then the full name will be widNode/ProductionServerAlias. This full name is the one you use in subsequent configuration windows.

    6. Click Save, and then click Save again.

  5. Click New.

You have created an authentication alias, which you use when you configure the adapter properties.



Related concepts:

User authentication

Feedback


Create the module

You create the module in IBM Integration Designer. The module allows you to define business objects that will be used by the project.

Start the external service wizard and follow this procedure to create a module.

  1. If IBM Integration Designer is not currently running, start it now.

    1. Click Start > Programs > IBM > IBM Integration Designer > IBM Integration Designer 8.0.

    2. If you are prompted to specify a workspace, either accept the default value or select another workspace.

      The workspace is a directory where IBM Integration Designer stores your project.

    3. Optional: When the IBM Integration Designer window is displayed, click Go to the Business Integration perspective.

  2. Right-click anywhere within the Business Integration workspace of the IBM Integration Designer window, and then select New > Module.

    Figure 1. Creating a module from the Business Integration section of the window

  3. name for the field, Module Name in the New Module window. For example, FTPOutboundModule. Leave the other options (Use default location and Open module assembly diagram) checked.

  4. Click Finish.

A new module is listed in the Business Integration window.


Feedback


Defining business objects

Predefine the business objects in Integration Designer that will be used by the project that you will create in the next topic.

To predefine new business objects using the business object editor.

  1. Expand the new module located inside the Business Integration section of the Integration Designer window.
  2. Right-click the Data Types folder and select New > Business Object.

  3. Type a new Name in the Business Object window. For example, Customer to create a customer business object.

  4. Click Finish. The new business object is added to the Data Types folder.

  5. Click the Add a field to a business object icon and add the necessary fields to the business object.

    Figure 1. Add Business object fields icon

  6. Click the Save icon.
  7. Repeat the previous steps for each business object to create.

The new business objects are defined.



Related concepts:

Business objects


Related reference:

Business object information

Feedback


Defining WAS environment variables

Use the administrative console of the runtime environment to define WebSphere Application Server environment variables.

To define a WAS environment variable, use the following procedure.

  1. Start the administrative console of the server.

  2. From the left menu, select Environment > WebSphere Variables.

  3. Select the scope for the environment variable. The scope specifies the level at which the resource definition is visible on the administrative console panel. The possible values are server, node, and cell. In this example, we are choosing Cell=widCell.

    Figure 1. Setting the scope for the environment variable

  4. Click New, and provide a name and a value for the environment variable. The name is the symbolic name that represents a physical path. The value is the absolute path the variable represents. In this example, the name is EVENT_DIRECTORY and the value is /home/user/event. You can use the Description field, which is optional, to describe the purpose of the variable.

    Figure 2. Providing a name and a value for the environment variable

  5. Click OK and save the changes.

An environment variable called EVENT_DIRECTORY is created, with the value /home/user/event and a scope of Cell=widCell. You can now use it in the external service wizard whenever you must specify the event directory.

Figure 3. The new environment variable EVENT_DIRECTORY displayed in the WebSphere Variables window



Related concepts:

WAS environment variables

Feedback


Create a simple service with the adapter pattern wizard

Adapter patterns provide a quick and easy way of creating a simple service with an adapter.

A module has already been created called RetrieveAFileModule and a business object called Customer has already been created. If you are using WebSphere Application Server environment variables to specify local files and directories, you have defined them using the BPM administrative console. The following adapter patterns are available for WebSphere Adapter for FTP:

Adapter pattern details

Adapter pattern Description
Inbound FTP pattern The FTP inbound pattern creates a service that retrieves a file in a specific directory on an FTP server. If the file is not in an XML format, you can specify a data handler that will transform from the file content format to business objects. The file content can be split if the content contains multiple copies of the data structure for processing.
Outbound FTP pattern The FTP outbound pattern creates a service that stores data in a file in a specific directory on an FTP server. If the required output format is not an XML format, you can specify a data handler that will transform the business object to the file content format.

In this example, you create an FTP inbound service that receives a file from the file system for processing. The completed service in this example will read in a file and split the contents into separate files based on a delimiter.

To create a service with the adapter pattern wizard:

  1. Open the Assembly diagram of RetrieveAFileModule

  2. Expand Inbound Adapters, drag and drop FTP into the Assembly diagram.

  3. Select Simple:Create an inbound FTP service to read from a remote file.

  4. Click Next.

    Figure 1. Select the Service Type or Registry window

  5. In the FTP service name window, specify a meaningful name, such as FTPInboundInterface and click Next.

  6. In the Business object and location window, click Browse and navigate to the Customer business object.

  7. Set the directory where you placed the input file, in this case the /home/user/event directory, and click Next. To use a WAS environment variable for this value, specify the name of the variable in braces, preceded by a $ symbol. For example: ${FTPINBOUNDEVENTS}.

    Figure 2. Business object and location window

  8. In the FTP server security credential window, select either Using an existing JAAS alias or Using user name and password and click Next.

  9. In the Input file format and file content split option window, accept the default XML input file format or select Other and specify a data handler to transform the data from your native format to the business object format.

  10. Select Split file content by delimiter and enter your delimiter, which is ####;\n in this example. Click Next.

    Figure 3. Input file format and file content split option window

  11. In the Archive directory and wrapper business object window, specify the Local archive directory, which is FTP\inboundarchive in this example. To use a WAS environment variable for this value, specify the name of the variable in braces, preceded by a $ symbol. For example: ${FTPINBOUNDARCHIVE}. Select Use a wrapper business object to contain additional input file information check box, to include the adapter-specific information. Click Finish.

The inbound service is created, which includes the following artifacts:

Artifact details

>Artifact >Name >Description
Export FTPInboundInterface The export exposes the module externally, in this case, to WebSphere Adapter for FTP.
Business objects Customer, CustomerWrapper The Customer business object contains the fields for customer data such as name, address, city, and state. The CustomerWrapper business object contains additional fields for adapter-specific information.
Interface FTPInboundInterface This interface contains the operation that can be invoked.
Operation emitCustomerInput emitCustomerInput is the only operation in the interface.

Figure 4. The Business Integration section of the Integration Designer window with the new artifacts


Feedback


Start the external service wizard

To begin the process of creating and deploying a module, you start the external service wizard in IBM Integration Designer. The wizard creates a project used to organize the files associated with the module.

Ensure that you have the information to establish a connection with the FTP server. For example, you need the name or IP address of the FTP server and the user ID and password to access it.

Start the external service wizard to create a project for the adapter in IBM Integration Designer. If you have an existing project, you can select it instead of having the wizard create one.

To start the external service wizard and create a project, use the following procedure.

  1. To start the external service wizard, go to the Business Integration perspective of IBM Integration Designer, and then click File > New > External Service.

  2. In the Select the Service Type or Registry window, expand Adapters.

  3. Expand FTP in Adapters and select Advanced: Create a FTP service using the complete wizard and click Next.

  4. In the Select an Adapter window, select the adapter name to create a project, or select an existing project to reuse it.

    • To create a project.

      1. Select IBM WebSphere Adapter for FTP (IBM : version), where version is the version of the adapter you want to use and click the CWYFT_FTPFile connector project. Click Next.

      2. In the Import a RAR File window, provide details about the project you want to create.

        1. In the Connector project field, accept the default project name or type a different name.

        2. In the Target runtime field, select the server where you want to deploy the module.

        3. Click Next.

    • To select an existing project, select the project folder under IBM WebSphere Adapter for FTP (IBM : version) and then click Next.

For a new project, the project is created and is listed in the Business Integration perspective. The wizard creates adapter artifacts in the specified project.


Feedback


Configure the module for outbound processing

To configure a module to use the adapter for outbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate the business object definitions and related artifacts.

  1. Set deployment and runtime properties Specify deployment and runtime properties the external service wizard uses to connect to the FTP server.
  2. Selecting a data type and operation name Use the external service wizard to select a data type and to name the operation associated with the data type. For outbound communications, the external service wizard gives you the choice of three different data types: user-defined type, generic FTP business object, and generic FTP business object with business graph. Each data type corresponds to a business object structure.
  3. Configure data binding and data handler Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in a file with information it receives in the business object.
  4. Set interaction specification properties and generating the service Interaction specification properties are optional. If you choose to set these properties, the values you specify are displayed as default values in all the parent FTP business objects generated by the external service wizard. Interaction specification properties control the interaction for an operation. While creating the artifacts for the module, the adapter generates an import file. The import file contains the operation for the top-level business object.
  5. Authentication using connection specification properties WebSphere Adapter for FTP uses connection properties either through Managed Connection Factory properties or a Javaâ„¢ Authentication and Authorization Services (JAAS) alias.

    To change the connection properties used for authentication with either one of these authentication methods, you can change the connection properties through the BPM administrative console and restart the Java EE application or change the JAAS security settings.

  6. Passing the connection parameters dynamically To pass the connection-related properties dynamically as part of the outbound request configure the connection specification class name and set the connection properties on the business graph.



Related concepts:

Outbound processing

Feedback


Set deployment and runtime properties

Specify deployment and runtime properties the external service wizard uses to connect to the FTP server.

Before you can set the properties in this section, you must have created your adapter module. It must appear in IBM Integration Designer below the adapter project. For more information about creating the adapter project, see Start the external service wizard.

To set deployment and runtime properties, follow this procedure. For more information about the properties in this topic, see Managed (J2C) connection factory properties.

  1. In the Select the Processing Direction window, select Outbound and click Next.
  2. The Set the Security and Configuration Properties window appears. In the Deploy connector project field, specify whether to include the adapter files in the module. Choose one of the following options:

    • With module for use by single application

      With the adapter files embedded in the module, you can deploy module to any application server. Use an embedded adapter when you have a single module using the adapter or when multiple modules need to run different versions of the adapter. By using an embedded adapter, you can upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.

    • On server for use by multiple applications

      If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  3. Define the following FTP system connection information for your module. See Managed (J2C) connection factory properties.

    • Host name - Specifies the host name of the FTP server.
    • Directory - Specifies the output directory on the FTP server. If the value of the Directory field is set to <HOME_DIR>, the adapter performs the outbound operations in the users home directory.

    • Verify output directory access permission - Specifies if the access permissions for the output directory must be verified before performing the outbound operation.
    • Protocol - Specifies the protocol used to connect to the FTP server. Following are the protocols that can be specified:

      • FTP - File Transfer Protocol
      • FTP over SSL - File Transfer Protocol over Secure Socket Layer
      • FTP over TLS - File Transfer Protocol over Transport Layer Security
      • SFTP - Secure shell File Transfer Protocol
    • Port number - Specifies the port number of the FTP server.

    Figure 1. Set the Security and Configuration Properties window

  4. Click Advanced to specify additional properties, service properties, data format options, properties that control working with a second FTP server, bidi formatting, a staging directory, logging and tracing, secure connection, and sequence file selection. See Managed (J2C) connection factory properties.

  5. Set the required security credentials in the Service Properties area:

    • To use a J2C authentication alias, select the Using an existing JAAS alias (recommended) field, and specify the name of the alias in the J2C Authentication Data Entry field. You can specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use managed connection properties, select the Using security properties from managed connection factory field, and type the values in the User name and Password fields.

    • User name - Specifies the name of the user who has privileges to connect to the FTP server and perform FTP operations. See User name property (userName).
    • Password - Specifies the password of the user who has privileges to connect to the FTP server and perform FTP operations. See Password property (password)
    • To administer the user name and password from other mechanism, select Other.

  6. If you have multiple instances of the adapter, expand Logging and tracing and set Adapter ID to a value that is unique for this instance. For more information about this property, see Adapter ID (AdapterID).

  7. Optional: In the Service properties section of the window, specify a Javaâ„¢ Authentication and Authorization Services (JAAS) alias for the adapter to use at run time. The specified alias is the authentication alias set up on the FTP server. The name is case-sensitive. For information about authentication alias, see Create an authentication alias.

  8. In the Data format options field, select one of the following:

    • Use default data binding 'FTPFileBaseDataBinding' for all operations

      A non-configured data binding for all the operations used in the service.

    • Use a data binding configuration for all operations

      A configured data binding for all the operations used in the service.

    • Specify a data binding for each operation

      No default binding is specified. You can select a specific data binding for each operation used in the service.

  9. Optional: Select the Change the logging properties for the wizard check box to specify the log file output location or define the level of logging for this module. For information about logging levels, see Configure logging and tracing.

The external service wizard now has the information to connect to the FTP server.


If you have selected the Data format options as Use default data binding 'FTPFileBaseDataBinding' for all operations or Specify a data binding for each operation, click Next to continue to work in the wizard to select a data type for the module and to name the operation associated with the data type.

If you have selected the Data format options as Use a data binding configuration for all operations, proceed to Configure data binding and data handler.



Next topic: Selecting a data type and operation name


Related concepts:

User authentication

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and to name the operation associated with the data type. For outbound communications, the external service wizard gives you the choice of three different data types: user-defined type, generic FTP business object, and generic FTP business object with business graph. Each data type corresponds to a business object structure.

Before you can perform the following steps, you must have specified the connection properties for the adapter to connect to the FTP server.

To select a data type and name the operation associated with it, follow this procedure.

  1. In the Add, Edit, or Remove Operations window, click Add to create an operation.

  2. In the Set the I/O Properties window, select an operation from the Operation kind drop-down list. In this example, the Create operation is selected.

  3. In the The data type for the input operation drop-down list, select a data type and click Next. In this example, the User defined data type is selected.

    If you select User defined type, you must provide a user-defined data binding to support it. The data bindings provided by the Generic FTP business object support only generic input types for the supported operations.

  4. To have the file name returned or to have True or False returned during Delete and ServerToServer operations, select the Enable response type for the operation check box. For Exists, List and Retrieve operations, a response type is required, and by default the Enable response type for the operation check box is selected.

  5. Click Next.

  6. In the Set the I/O Properties window, type a name for the operation in the Operation name field. Name the operation something meaningful. If this module is going to be used to create a customer record, name it something like createCustomer. For more information about the types of operations the adapter can perform, see Supported operations.

    Names cannot contain spaces.

    Figure 1. Set the I/O Properties window

  7. In the Set the Operation Input area, select New for the Input Type field to create a data type. To use an existing data type, click Browse and select it.

A data type is defined for the module and the operation associated with this data type is named.


If you choose to add and configure a data binding to be used with the module, Select Use a data format configuration from the Data format options list. Click Select next to the Data Format field. Proceed with configuring the data binding with the steps mentioned in Configuring the data binding and data handler topic.

If you choose to use the default data binding, proceed to Set interaction specification properties and generating the service.



Previous topic: Set deployment and runtime properties


Next topic: Configure data binding and data handler

Feedback


Configure data binding and data handler

Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in a file with information it receives in the business object.

You must have selected a data type and chosen a configuration name to be associated with the data type.

Data bindings can be configured before running the external service wizard using IBM Integration Designer. To configure the data bindings, select New > Configure Binding Resource in IBM Integration Designer and complete the data binding windows described in this documentation.

To add and configure a data binding for the module, follow this procedure.

  1. In the Select a Data Format Transformation window, select FTPFileBaseDataBinding from the list. To configure a custom data binding, select Select your custom data format transformation from the workspace and select the implementation class name. Click Next.

    Figure 1. Select a Data Format Transformation window

    Set the data handler which performs the conversions between a business object and a native format when you select a data type that contains the business objects.

  2. To configure a data handler, in Set the Data Transformation Properties window, select the Binding Type as DataHandler.

  3. Click Select next to Data handler configuration option.

    Figure 2. Set the Data Transformation Properties window

  4. In the Select a Data Format Transformation window, select the required Data handler from the list. To configure a custom data handler, select Select your custom data format transformation from the workspace and select the implementation class name.

    Figure 3. Select a Data Format Transformation window

  5. Set the Module, Namespace, Folder, and Name for the data binding configuration in the Configure a Data Transformation Configuration window.

    Figure 4. Configure a New Data Transformation window

  6. Click Finish.

A data binding and data handler is configured for use with the module.


From the current external service wizard window, proceed to the next window.



Previous topic: Selecting a data type and operation name


Next topic: Set interaction specification properties and generating the service

Feedback


Set interaction specification properties and generating the service

Interaction specification properties are optional. If you choose to set these properties, the values you specify are displayed as default values in all the parent FTP business objects generated by the external service wizard. Interaction specification properties control the interaction for an operation. While creating the artifacts for the module, the adapter generates an import file. The import file contains the operation for the top-level business object.

To set interaction specification properties and generate artifacts, follow this procedure. See Wrapper and interaction specification properties.

The values set in the business object wrapper properties take precedence over the interaction specification properties, even if a NULL value is set. If the values are not set in the business object wrapper properties, then the adapter uses the values set in the interaction specification properties. The adapter uses the values set in the Managed (J2C) connection factory properties if the values are not set in the wrapper and the interaction specification properties.

  1. To set interaction specification properties, populate the fields in the Operations window. You can also click Advanced to add additional property details.

    1. Type values for any fields you want to set as defaults.

    2. Select the Generate a unique file check box, to enable the adapter to generate a unique file name during the outbound Create operation. See Generate a unique file property (GenerateUniqueFile).

    3. Click Next.

      Figure 1. Interaction specification properties

  2. In the Generate Service window, specify a name for the interface. The specified name is displayed in the IBM Integration Designer assembly diagram.

    Figure 2. Set the Name and Location window

  3. Click Finish. The IBM Integration Designer assembly diagram displays the interface you created.

    Figure 3. Interface in Integration Designer

  4. Optional: Repeat the previous steps to add all other required operations, including the bindings, data handlers, and interaction specifications.

IBM Integration Designer generates the artifacts and the import. The outbound artifacts that are created are visible in the IBM Integration Designer Project Explorer under your module.


Deploy the module to the server.



Previous topic: Configure data binding and data handler


Next topic: Authentication using connection specification properties

Feedback


Passing the connection parameters dynamically

To pass the connection-related properties dynamically as part of the outbound request configure the connection specification class name and set the connection properties on the business graph.

  1. FTP adapter import interface, for example, FTPImport, must be created for the required outbound operations by running the external service wizard.
  2. The input data type for each of the outbound operation must be configured to use the business graph of the business object. For example, the input data type of the operations can be FTPFileBG or CustomerWrapperBG.

    The business graph implementation has a child business object, ‘properties' defined as an element in the business graph schema definition. The connection properties must be set in the dataobject ‘properties' of the business graph.

To pass the connection-related properties dynamically as part of the outbound request, follow this procedure.

  1. Configure the ConnectionSpec class name in the FTP Import created.

    1. Right-click the FTP adapter import in the assembly diagram and select Show in > Properties view.

    2. In the Properties tab, select Binding > End-point Configuration.

    3. In the Connection Spec properties tab, select ConnectionSpec class name as com.ibm.j2ca.ftp.FTPFileConnectionSpec

  2. Set the Resource authentication field in Security Attributes to Application.

    1. Select Security Attributes from Binding properties.

    2. Set the Resource authentication property to Application from Advanced properties. The default value is Container.

    When the Resource Authentication property is set to Application, the Java EE component runs a programmatic sign-on to the FTP server. The application component passes security information, such as user name and password, through the ConnectionSpec instance.

  3. Set the Connection properties in the BusinessGraph within the properties child business object.

    For the adapter to accept the connection parameters dynamically during an outbound request, the application component must set the connection parameters on the business graph data object of the business object.

    The connection properties set on the business graph are prefixed as "CS" to identify them as ConnectionSpec properties. For example, you can set the user name and password to 'CSuserName' and 'CSpassword' in the properties element of the BusinessGraph to set the values of connection properties.

    The host name, protocol, or port number values are not accepted through the ConnectionSpec properties. The adapter accepts only authentication-related properties of the user, such as user name, password, and truststore, to be passed dynamically during an outbound request.

The connection parameters are configured.


Create an interface and a Javaâ„¢ component, and then deploy the application onto the BPM.



Previous topic: Authentication using connection specification properties


Related concepts:

Authentication using connection specification properties

Feedback


Create an interface

After passing and configuring the connection parameters, during the outbound processing, create an application component to send the outbound request along with the connection properties to test the functionality.

You have run the external service wizard to create the outbound interface. The new FTPImport interface has multiple input properties to pass the connection properties.

You create an application component to send the outbound request using the connection properties. The new FTPImport interface has multiple input properties to pass the connection properties. To create an interface to test the functionality, use the following procedure.

  1. From the Business Integration view, click File > New > Interface. The New Interface Wizard is displayed.
  2. name, for example, FTPDynamicConnectionInterface, for the new interface, and click Finish.

  3. Add a "Request Response" operation. It matches the operation in the FTPOutboundInterface with additional input parameters for the connection properties. The input parameters of the outbound operation contains the BusinessGraph object and a set of connection properties for which the value is set in the BusinessGraph.

A new interface is created.


Create a Javaâ„¢ component. See Create a Java component



Related concepts:

Authentication using connection specification properties

Feedback


Create a Java component

After creating an interface and testing it, create a Javaâ„¢ component to set the values for the properties element.

Ensure that you have created an interface that has multiple input properties to pass the connection properties.

Create a Java component and set the connection-related properties to pass it as input to the interface on the business graph object. To create a Java component, use the following procedure.

  1. Create a Java component in the assembly diagram.
  2. Wire the Java component to the FTPOutboundInterface import. The Java component interface, that is, FTPDynamicConnectionInterface is created. To create the Java component, click the Java component. Click the 'add an interface' icon and select the interface, FTPDynamicConnectionInterface.

  3. Set the connection-related properties, which are sent as input to the interface on the BusinessGraph object, for the implementation of the Java component.

    The following sample code is the Java EE component implementation that sets the connection parameters on the properties business object of the BusinessGraph: 

    public DataObject createFTPFile(DataObject createFTPFileWrapperBG,String userName,
   String password, String privateKeyFilePath,
   String passphrase) {

 DataObject prop = createFTPFileWrapperBG.getDataObject("properties");

 // check if they already created this child object or not if(prop == null) {
  // Create the "properties" business object   prop = createFTPFileWrapperBG.createDataObject("properties");
 }

 // Setting the property 'userName' to connectionSpec
 // Note the username property is prefixed by CS
 prop.setString("CSuserName", userName); 

 // Setting the property 'password' to connectionSpec
 // Note the password property is prefixed by CS
 prop.setString("CSpassword", password);

 //Setting the property ‘privateKeyFilePath' which is used for SFTP protocol to connection spec  prop.setString("CSprivateKeyFilePath", privateKeyFilePath);

 //Setting the property ‘passphrase' which is used for SFTP protocol to connection spec  prop.setString("CSpassphrase", passphrase);


 // invoke the Adapter  Service serv= locateService_SFTPImportPartner();
 Object boReturn= serv.invoke(
   "create",
   createFTPFileWrapperBG);

 // return the result BO that we got back from the FTP Adapter  return ((DataObject)boReturn).get(0);

  }

    During run time, the connection properties values are set on the input parameters of the Java component. This in turn is set on the dataobject 'properties' of the BusinessGraph by the above displayed code. The EIS binding then passes the connection properties to the adapter which is set on the dataobject 'properties' by populating it in the ConnectionSpec bean. The adapter uses the ConnectionSpec properties to get a connection to the EIS.

    For more information about EIS binding, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r0mx/index.jsp?topic=/com.ibm.websphere.wesb.doc/doc/cadm_dynamicheader.html. For information about how to configure dynamic authentication, see http://www.ibm.com/developerworks/websphere/library/techarticles/0608_martinez/0608_martinez.html.

A Java component is created.


Deploy the application onto the BPM and send an outbound request, which includes the connection parameters using the IBM Integration Designer test client. As a result, the adapter uses these connection parameters from the request to create the connection. Any value specified in the Managed Connection Factory properties is ignored by the adapter.



Related concepts:

Authentication using connection specification properties

Feedback


Configure the module for inbound processing

To configure a module to use the adapter for inbound processing, use the external service wizard in IBM Integration Designer to build business services, specify data transformation processing, and generate business object definitions and related artifacts.

  1. Set deployment and runtime properties Specify deployment and runtime properties the external service wizard uses to connect to the FTP server.
  2. Selecting a data type and operation name Use the external service wizard to select a data type and to name the operation associated with the data type. For inbound communications, the external service wizard gives you the choice of three different data types: user-defined type, generic FTP business object, and generic FTP business object with business graph. Each data type corresponds to a business object structure.
  3. Configure the data binding and data handler Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in a file with information it receives in the business object.
  4. Generating the service While creating artifacts for the module, the adapter generates an export file. The export file contains the operation for the top-level business object.



Related concepts:

Inbound processing

Feedback


Set deployment and runtime properties

Specify deployment and runtime properties the external service wizard uses to connect to the FTP server.

Before you can set the properties in this section, create your adapter module. It must be displayed in IBM Integration Designer below the adapter project. For more information about creating the adapter project, refer to Start the external service wizard.

To set deployment and runtime properties, follow this procedure. For more information about the properties in this topic, refer to Activation specification properties.

  1. In the Select the Processing Direction window, select Inbound and click Next.

  2. In the Deploy connector project field, specify whether to include the adapter files in the module. Choose one of the following options:

    • With module for use by single application

      With the adapter files embedded in the module, you can deploy the module to any application server. Use an embedded adapter when you have a single module using the adapter or when multiple modules need to run different versions of the adapter. By using an embedded adapter, you can upgrade the adapter in a single module without the risk of destabilizing other modules by changing their adapter version.

    • On server for use by multiple applications

      If you do not include the adapter files in a module, install them as a stand-alone adapter on each application server where you want to run the module. Use a stand-alone adapter when multiple modules can use the same version of the adapter and you want to administer the adapter in a central location. A stand-alone adapter can also reduce the resources required by running a single adapter instance for multiple modules.

  3. Define the following FTP system connection information for your module. For more information, refer to Activation specification properties.

    • Host name - Specifies the host name of the FTP server.
    • Remote directory - Specifies the directory on the FTP server, where the adapter polls and picks up files. If the Remote directory is set to <HOME_DIR>, the adapter polls for event files in the home directory.

    • Verify remote directory access permission - Specifies if the access permissions for the remote directory must be verified before performing the inbound operation.
    • Local directory - Specifies the directory on the adapter workstation where the event files are downloaded from the FTP server.
    • Protocol - Specifies the protocol used to connect to the FTP server. Following are the protocols that can be specified:

      • FTP - File Transfer Protocol
      • FTP over SSL - File Transfer Protocol over Secure Socket Layer
      • FTP over TLS - File Transfer Protocol over Transport Layer Security
      • SFTP - Secure shell File Transfer Protocol
    • Port number - Specifies the port number of the FTP server.

    Figure 1. Set the Security and Configuration Properties window

  4. To filter the inbound event file by configuring rules, click Add or Edit in the Rule editor table. The rule constitutes three parameters, namely, Property type, Operator and Value.

    Figure 2. Adding or editing a rule

    1. Select any of the following metadata filtering property types from Property type list.

      • FileName
      • FileSize
      • LastModified

    2. Select the operator for the property type from the Operator list. Each of the property type metadata has its own operators.

      1. FileName contains the following operators:

        • Matches_File_Pattern (matches pattern)
        • Matches_RegExp (matches regular expression)

      2. FileSize metadata contains the following operators:

        • Greater than
        • Less than
        • Greater than or equal to
        • Less than or equal to
        • Equal to
        • Not equal to

      3. LastModified metadata contains the following operators:

        • Greater than
        • Less than
        • Greater than or equal to
        • Less than or equal to
        • Equal to
        • Not equal to

    3. Type the value for filtering the event file in the Value column. You must enter a valid Javaâ„¢ regular expression in value for Matches_RegExp operator.

    To configure multiple rules, select END-OF-RULE option for each rule from the Property type list.

    The rules are grouped by using the logical OR operator, unless END-OF-RULE is selected in the property field. If an END-OF-RULE is selected between expressions (an expression can be a single rule or multiple rules grouped by an OR operator), it will be grouped using the logical AND operator. For example, If the rule A (FileName) is grouped with rule B (FileSize) using the logical OR operator, and on selecting the END-OF-RULE option, this expression will be grouped with another rule C (LastModified) using an AND operator. This can be represented as follows: ((A) OR (B)) AND (C)

    For more information see, Rule editor to filter files (ruleTable).

  5. Optional: Specify advanced properties by clicking Advanced. Expand each of the advanced sections to review the properties.

    • Event polling configuration
    • Event delivery configuration
    • Event persistence configuration

    • Additional configuration
    • FTP archiving configuration
    • Socks proxy server connection information
    • Secure configuration
    • Bidi properties
    • Logging and tracing properties

    The following sections describe the options that are available in the advanced property groups.

  6. Set the required security credentials in the Service Properties area:

    • To use a J2C authentication alias, select the Using an existing JAAS alias (recommended) field, and specify the name of the alias in the J2C Authentication Data Entry field. You can specify an existing authentication alias or create one at any time before deploying the module. The name is case-sensitive and includes the node name.
    • To use activation specification properties, select the Using security properties from the activation specification field, and type the values in the User name and Password fields.

    • User name - Specifies the name of the user who has privileges to connect to the FTP server and perform FTP operations. See User name property (userName).
    • Password - Specifies the password of the user who has privileges to connect to the FTP server and perform FTP operations. See Password property (password).
    • To administer the user name and password from other mechanism, select Other.

  7. Select one of the options from the Function selector field. A function selector assigns incoming messages or requests to the correct operation on the service.

    • Function selector options

      For example, select Use a Function Selector configuration. If choosing to use this option, click Next.

    • Function selector

      If choosing this option:

      1. Click Select next to the Function Selector field.

        Figure 4. Set the Security and Configuration Properties window

      2. In the Select Function Selector window, select the option, Use existing function selector from the list. A list of available function selectors is displayed. Select the function selector (this example uses FilenameFunctionSelector properties). Click Next.

        The EIS function name is not available in the external service wizard. To specify a value other than the default that is generated by the adapter, you can edit it using the assembly editor.

  8. Click Finish in the New Function Selector Configuration window.

  9. Click Next in the Service Configuration Properties window.

The external service wizard now has the information it needs to connect to the FTP server.


If you have selected the Data format options as Use default data binding 'FTPFileBaseDataBinding' for all operations or Specify a data binding for each operation, click Next to continue to work in the wizard to select a data type for the module and to name the operation associated with the data type.

If you have selected the Data format options as Use a data binding configuration for all operations, proceed to Configure data binding and data handler.



Next topic: Selecting a data type and operation name


Related concepts:

User authentication

Known issues in editing the Rule Table

Inbound processing


Related reference:

Activation specification properties

Feedback


Selecting a data type and operation name

Use the external service wizard to select a data type and to name the operation associated with the data type. For inbound communications, the external service wizard gives you the choice of three different data types: user-defined type, generic FTP business object, and generic FTP business object with business graph. Each data type corresponds to a business object structure.

You must have specified the connection properties for the adapter to connect to the FTP server before you can complete the following steps.

To select a data type and name the operation associated with it, follow this procedure.

  1. In the Operations window, click Add.

  2. In the Add Operations window, select The data type for the operation input, and click Next. If you select User defined type, you must provide a user-defined data binding to support it. The Generic FTP business object provided data binding only supports generic input types for the supported operations.

  3. In the Operation window, type a name in the Operation name field or keep the default emitFTPFile name.

    Names cannot contain spaces.

A data type is defined for the module and the operation associated with the data type is named.


If you choose to add and configure a data binding to be used with the module, Select Use a data format configuration from the Data format options list. Click Select next to the Data Format field. Proceed with configuring the data binding with the steps mentioned in Configuring the data binding and data handler topic.

If you choose to use the default data binding, proceed to Generating the service.



Previous topic: Set deployment and runtime properties


Next topic: Configure the data binding and data handler

Feedback


Configure the data binding and data handler

Each data type has an equivalent data binding used to read the fields in a business object and fill the corresponding fields in a file. In the external service wizard, you add a data binding to your module and configure it to correspond with your data type. This way, the adapter knows how to populate the fields in a file with information it receives in the business object.

You must have selected a data type and chosen a configuration name to be associated with the data type.

Data bindings can be configured before running the external service wizard using IBM Integration Designer. To do this, select New > Configure Binding Resource in IBM Integration Designer and complete the data binding windows described in this documentation.

To add and configure a data binding for the module, follow this procedure.

  1. In the Select a Data Format Transformation window, select FTPFileBaseDataBinding from the list. To configure a custom data binding, select Select your custom data format transformation from the workspace and select the implementation class name. Click Next.

    Figure 1. Select a Data Format Transformation window

    Set the data handler which performs the conversions between a business object and a native format when you select a data type that contains the business objects.

  2. To configure a data handler, in Set the Data Transformation Properties window, select the Binding Type as DataHandler.

  3. Click Select next to Data handler configuration option.

    Figure 2. Set the Data Transformation Properties window

  4. In the Select a Data Format Transformation window, select the required Data handler from the list. To configure a custom data handler, select Select your custom data format transformation from the workspace and select the implementation class name.

    Figure 3. Select a Data Format Transformation window

  5. Set the Module, Namespace, Folder, and Name for the data binding configuration in the Configure a New Data Transformation window.

    Figure 4. Configure a New Data Transformation window

  6. Click Finish.

A data binding and data handler is configured for use with the module.


From the current external service wizard window, proceed to the next window.



Previous topic: Selecting a data type and operation name


Next topic: Generating the service

Feedback


Generating the service

While creating artifacts for the module, the adapter generates an export file. The export file contains the operation for the top-level business object.

To generate artifacts, follow this procedure.

  1. Click Next in the Operations window.

  2. In the Generate Service window, supply a name for the interface. This is the name that is displayed in the Integration Designer assembly diagram.

  3. Click Finish. The Integration Designer assembly diagram opens and the interface you created is displayed.

The Integration Designer generates the artifacts and an export. The inbound artifacts that are created are visible in the Integration Designer Project Explorer under your module.


Deploy the module to the server.



Previous topic: Configure the data binding and data handler


Related reference:

Configuration properties

Resource adapter properties

Managed (J2C) connection factory properties

Activation specification properties

Globalization

Feedback


Change interaction specification properties

To change interaction specification properties for your adapter module after generating the service, use the assembly editor in IBM Integration Designer.

You must have used the external service wizard to generate a service for the adapter.

You might want to change interaction specification properties after you have generated a service for the adapter. Interaction specification properties, which are optional, are set at the method level, for a specific operation on a specific business object. The values you specify appear as defaults in all parent business objects generated by the external service wizard. You can change these properties before you export the EAR file. You cannot change these properties after you deploy the application.

To change the interaction specification properties, use the following procedure:

  1. From the Business Integration perspective of IBM Integration Designer, expand the module name.

  2. Expand Assembly Diagram and double-click the interface.

  3. Click the interface in the assembly editor. The module properties are displayed.

  4. Click the Properties tab. You can also right-click the interface in the assembly diagram and click Show in Properties.

  5. Under Binding, click Method bindings. The methods for the interface are displayed, one for each combination of business object and operation.

  6. Select the method whose interaction specification property you want to change.

  7. Click Advanced and change the property in the Generic tab. Repeat this step for each method whose interaction specification property you want to change.

The interaction specification properties associated with your adapter module are changed.

If the changes are not reflected even after you have restarted the application, restart the server so the changes are reflected.


Deploy the module.



Related reference:

Wrapper and interaction specification properties

Feedback


Converting business objects to COBOL copybook files during outbound processing

Use the external service wizard in Integration Designer to generate business object definitions from a COBOL program source file. These business object definitions are used during outbound processing.

Before you perform this task, make sure that:

  1. You have created a module in Integration Designer.
  2. The COBOL program source file (.ccp file) is in a local directory on your workstation.

  3. If you are going to generate a wrapper business object definition, you have imported the adapter RAR file into your workspace.

Use the external service wizard to generate a business object definition for a COBOL program source file. After you have generated the business object definition, you can run the external service wizard again to generate a wrapper business object definition from the generated business object.

  1. To generate the business object for the COBOL program source file:

    1. In the Business Integration section of the window, right-click the module and select New > Business Object From External Data.

    2. In the Select an Input Source window, expand Languages and select Cobol.

    3. Click Next.

      Figure 1. Select an Input Source window

    4. In the Provide Details for the Mapping window, ensure the Selected mapping value is COBOL to Business Object. Click Browse and select the .ccp file. For example, taderc99.ccp can be the name of the .ccp file.
    5. Click Next.

    6. In the Select Data Structures window, click Find. The new business object called DFHCOMMAREA is displayed.

    7. Select DFHCOMMAREA and click Next.

    8. Click Finish.

    A business object called DFHCOMMAREA is created in the module.

  2. Optional: Generate a wrapper business object definition. Wrapper business object definitions wrap existing business object definitions with additional function. The generation of wrapper business object definitions is optional. The option to generate wrapper business object definitions is displayed only if the adapter RAR file is imported into the workspace.

    To generate wrapper business object definitions, then you must generate them before running the external service wizard.

    1. In the Business Integration section of the window, right-click the module and select New > Business Object From External Data.

    2. In the Select an Input Source window, expand Adapters, select the adapter connector project for which you want to generate the wrapper business object. In this case, select FTP.

    3. Click Next.

    4. In the Set the Properties window, click Browse and select the business object created in Step 1, for example, DFHCOMMAREA, for the data type.

    5. To generate a business graph, select the Generate business graph for each business object check box. For generating the retrieve wrapper, select the Generate retrieve container to retrieve multiple business objects check box.

      Figure 2. Set the Properties window

    6. Click Finish.

    A wrapper business object and a business graph, called DFHCOMMAREAWrapper and DFHCOMMAREAWrapperBG, respectively, are listed for the current module in the Business Integration window. If the user has selected Generate business graph for each business object and Generate retrieve container to retrieve multiple business objects, then a business object called DFHCOMMAREARetrieveWrapper and a business graph called DFHCOMMAREARetrieveWrapperBG are also listed for the current module in the Business Integration window.

    Figure 3. The wrapper business object and the business graph listed in the Business Integration window

  3. Generate the required artifacts for the COBOL copybook outbound module. This example shows the configuration for a Create operation.

    1. In the Business Integration section of the window, right-click the module and select New > External Service.

    2. Select FTP from Adapters and click Next.

    3. In the Select an Adapter window, select IBM WebSphere Adapter for FTP (IBM : version) where version is the version of the adapter you want to use, and click the CWYFT_FTPFile connector project. Click Next.

    4. In the Processing Direction window, select Outbound.

    5. Click Next.

    6. From the Service Configuration Properties window, in the Data format options list, select Use COBOL, C or PL/I data binding.

      This is not a data binding, but a data binding generator. The tool generates the appropriate data binding code for you in the current module.

      Figure 4. Set the Security and Configuration Properties window

    7. Set the other required properties for the outbound operation, and click Next.

    8. In the Operations window, click Add and then Create. For the retrieve operation, select Retrieve. Select the data type as User defined type from the list and click Next.
    9. Browse for the input type (either DFHCOMMAREA, DFHCOMMAREAWrapper, or DFHCOMMAREAWrapperBG) and click OK. For the Retrieve operation, browse for the appropriate output type (either DFHCOMMAREA, DFHCOMMAREARetrieveWrapper, or DFHCOMMAREARetrieveWrapperBG).

      Figure 5. The Data Type Selection window

    10. Click Next.

    The data bindings used by the COBOL copybook, WSDL files, import files, and other artifacts are generated. See the Project Explorer window for the generated data binding classes.

    Figure 6. Data bindings used by the COBOL copybook, WSDL files, import files, and other artifacts

A business object, a wrapper business object, and a business graph are created for the COBOL program source file for the outbound module. Artifacts are generated for an outbound Create operation that uses the COBOL copybook data binding. This module can be deployed on IBM Business Process Manager and tested for the Create operation.

To generate artifacts for other supported operations (Append and Overwrite), follow the same steps, beginning with Step 3(h).


Deploy the module.


Feedback


Converting COBOL copybook files to business objects during inbound processing

Use the external data wizard in IBM Integration Designer to generate business object definitions from a COBOL program source file. These business object definitions are used during inbound processing.

Before you perform this task, make sure that:

  1. You have created a module in IBM Integration Designer.
  2. The COBOL program source file (.ccp file) is in a local directory on your workstation.
  3. You have created a local event directory.

  4. If you are going to generate a wrapper business object definition, you must have imported the adapter RAR file into your workspace.

Use the external data wizard to generate a business object definition for a COBOL program source file. After you have generated the business object definition, you can optionally rerun the external data wizard to generate a wrapper business object definition from the generated business object.

  1. Generate the business object definition for the COBOL program source file.

    1. In the Business Integration section of the window, right-click the module and select New > Business Object From External Data.

    2. In the Select an Input Source window, expand Languages and select COBOL.

    3. Click Next.

      Figure 1. Select an Input Source window

    4. In the Provide Details for the Mapping window, ensure the Selected mapping value is COBOL to Business Object. Click Browse and select the .ccp file. For example, taderc99.ccp can be the name of the .ccp file.
    5. Click Next.

    6. In the Select Data Structures window, click Find. The new business object, called DFHCOMMAREA is displayed.

    7. Select DFHCOMMAREA and click Next.

    8. Click Finish.

    A business object, called DFHCOMMAREA is created in the module.

  2. Optional: Generate a wrapper business object definition. Wrapper business object definitions wrap existing business object definitions with additional function. The generation of wrapper business object definition is optional. The option to generate wrapper business object definitions are displayed only if the adapter RAR file is imported into the workspace.

    To generate wrapper business object definitions, then you must generate them before running the external service wizard.

    1. In the Business Integration section of the window, right-click the module and select New > Business Object From External Data.

    2. In the Select an Input Source window, expand Adapters, select the adapter connector project for which you want to generate the wrapper business object. In this case, select FTP.

    3. Click Next.

    4. In the Select an Adapter window, select the connector project in which the new business object was saved and click Next.

    5. In the Set the Properties window, click Browse and select the business object created in Step 1, for example, DFHCOMMAREA, for the data type.

    6. To generate a business graph, select the Generate business graph for each business object check box.

      Figure 2. Set the Properties window

      Generate retrieve container to retrieve multiple business objects is applicable only for outbound retrieve operation.

    7. Click Finish.

    A wrapper business object and a business graph, called DFHCOMMAREAWrapper and DFHCOMMAREAWrapperBG, respectively are listed for the current module in the Business Integration window.

    Figure 3. The wrapper business object and the business graph listed in the Business Integration window

  3. Generate the required artifacts for the COBOL copybook inbound module.

    1. In the Business Integration section of the window, right-click the module and select New > External Service.

    2. Select FTP under Adapters and click Next.

    3. In the Select an Adapter window, select IBM WebSphere Adapter for FTP (IBM : version) where version is the version of the adapter you want to use, and click the CWYFT_FTPFile connector project. Click Next.

    4. In the Processing Direction window, select Inbound and click Next.

    5. Click Browse and select the event directory.

    6. For the Function selector, select the default value.

    7. In the Data format options list, select Use COBOL, C or PL/I data binding option.

      This is not a data binding, but a data binding generator. The tool generates the appropriate data binding code in the current module.

      Figure 4. Set the Security and Configuration Properties window

    8. If the input file contains multiple COBOL program source files, you can enable file splitting by specifying a size or delimiter. To enable file splitting, click Advanced and then click Additional configuration. To enable file splitting by size, you must provide the correct length of each COBOL program source file. You can either open the business object in a text editor and add the maximum length, or view the content size of DFHCOMMAREA at the top of the file. See Specify criteria to split file content property (splitCriteria).

    9. Click Next.

    10. In the Operations window, click Add.

    11. In the Operations window, select User defined type as the data type. Click Next.

    12. For the input type, click Browse and select the generated business object (DFHCOMMAREA). Click OK.

      Figure 5. Set the I/O Properties window

    13. Click Finish.

    14. Click Next and then Finish.

    The data bindings used by COBOL copybook, WSDL files, export files, and other artifacts are generated. See the Project Explorer window for the generated data binding classes.

    Figure 6. Data bindings used by COBOL copybook, WSDL files, export files, and other artifacts

A business object, a wrapper business object, and a business graph are created for the COBOL program source file for the inbound module. Artifacts are generated for an inbound operation that uses COBOL copybook data binding. This module can be deployed on IBM Business Process Manager and tested for an inbound operation.


Deploy the module.



Related reference:

Activation specification properties

Feedback


Deploy the module

Deploy a module to place the files that make up your module and adapter into an operational environment for production or testing. In IBM Integration Designer, the integrated test environment features runtime support for BPM or WebSphere Enterprise Service Bus, or both, depending on the test environment profiles that you selected during installation.


Feedback


Deployment environments

There are test and production environments into which you can deploy modules and adapters.

In IBM Integration Designer, you can deploy your modules to one or more servers in the test environment. This is typically the most common practice for running and testing business integration modules. However, you can also export modules for server deployment on IBM Business Process Manager or WebSphere Enterprise Service Bus as EAR files using the administrative console or command-line tools.


Feedback


Deploy the module for testing

In IBM Integration Designer, you can deploy a module that includes an embedded adapter to the test environment and work with server tools that enable you to perform such tasks as editing server configurations, starting, and stopping servers and testing the module code for errors. The testing is generally performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Generating and wiring a target component for testing inbound processing Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.
  2. Add the module to the server In IBM Integration Designer, you can add modules to one or more servers in the test environment.
  3. Testing the module for outbound processing using the test client Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.


Feedback


Generating and wiring a target component for testing inbound processing

Before deploying to the test environment a module that includes an adapter for inbound processing, you must first generate and wire a target component. This target component serves as the destination to which the adapter sends events.

You must have generated an export module, using the external service wizard.

Generating and wiring a target component for inbound processing is required in a testing environment only. It is not necessary when deploying the adapter in a production environment.

The target component receives events. You wire the export to the target component (connecting the two components) using the assembly editor in IBM Integration Designer. The adapter uses the wire to pass event data (from the export to the target component).

  1. Create the target component.

    1. From the Business Integration perspective of IBM Integration Designer, expand Assembly Diagram and double-click the export component. If you did not change the default value, the name of the export component is the name of your adapter + InboundInterface.

      An interface specifies the operations that can be called and the data that is passed, such as input arguments, returned values, and exceptions. The InboundInterface contains the operations required by the adapter to support inbound processing and is created when you run the external service wizard.

    2. Create a new component by expanding Components, selecting Untyped Component, and dragging the component to the Assembly Diagram.

      The cursor changes to the placement icon.

    3. Click the component to have it displayed in the Assembly Diagram.

  2. Wire the components.

    1. Click and drag the export component to the new component.

      Save the assembly diagram. Click File > Save.

  3. Generate an implementation for the new component.

    1. Right-click on the new component and select Generate Implementation > Java.

    2. Select (default package) and click OK. This creates an endpoint for the inbound module.

      The Javaâ„¢ implementation is displayed in a separate tab.

    3. Optional: Add print statements to print the data object received at the endpoint for each of the endpoint methods.

    4. Click File > Save to save the changes.


Continue deploying the module for testing.



Next topic: Add the module to the server

Feedback


Add the module to the server

In IBM Integration Designer, you can add modules to one or more servers in the test environment.

If the module you are testing uses an adapter to perform inbound processing, generate and wire a target component to which the adapter sends the events.

In order to test your module and its use of the adapter, you need to add the module to the server.

  1. Conditional: If there are no servers in the Servers view, add and define a new server by performing the following steps:

    1. Place your cursor in the Servers view, right-click, and select New > Server.

    2. From the Define a New Server window, select the server type.

    3. Configure servers settings.

    4. Click Finish to publish the server.

  2. Add the module to the server.

    1. Switch to the servers view. In IBM Integration Designer, select Windows > Show View > Servers.

    1. Start the server. In the Servers tab in the lower-right pane of the IBM Integration Designer screen, right-click the server and then select Start.

  3. When the server status is Started, right-click the server and select Add and Remove Projects.

  4. In the Add and Remove Projects screen, select your project and click Add. The project moves from the Available projects list to the Configured projects list.

  5. Click Finish. This deploys the module on the server.

    The Console tab in the lower-right pane displays a log while the module is being added to the server.


Test the functionality of your module and the adapter.



Previous topic: Generating and wiring a target component for testing inbound processing


Next topic: Testing the module for outbound processing using the test client

Feedback


Testing the module for outbound processing using the test client

Test the assembled module and adapter for outbound processing using the IBM Integration Designer integration test client.

You need to add the module to the server first.

Testing a module is performed on the interface operations of your components, which enables you to determine whether the components are correctly implemented and the references are correctly wired.

  1. Select the module you want to test, right-click on it, and select Test > Test Module.
  2. Follow the instructions for Testing modules and components at the Related tasks link of this topic.


If you are satisfied with the results of testing your module and adapter, you can deploy the module and adapter to the production environment.



Previous topic: Add the module to the server


Related tasks:

Testing modules and components in WebSphere Integration Developer

Feedback


Deploy the module for production

Deploy a module created with the external service wizard to IBM Business Process Manager or WebSphere Enterprise Service Bus in a production environment is a two-step process. First, you export the module in IBM Integration Designer as an enterprise archive (EAR) file. Second, you deploy the EAR file using the BPM or WebSphere Enterprise Service Bus administrative console.

  1. Install the RAR file (for modules using stand-alone adapters only) If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Javaâ„¢ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).
  2. Export the module as an EAR file Using IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.
  3. Install the EAR file Installing the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.



Previous topic: Configure the module for deployment


Next topic: Configure logging and tracing

Feedback


Install the RAR file (for modules using stand-alone adapters only)

If you chose not to embed the adapter with your module, but instead choose to make the adapter available to all deployed applications in the server instance, you need to install the adapter in the form of a RAR file to the application server. A RAR file is a Javaâ„¢ archive (JAR) file used to package a resource adapter for the Java EE Connector Architecture (JCA).

You must set Deploy connector project to On server for use by multiple adapters in the Set the Service Generation and Deployment Properties window of the external service wizard.

Install the adapter in the form of a RAR file results in the adapter being available to all Java EE application components running in the server run time.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click Install RAR.

    Figure 1. The Install RAR button on the Resource adapters page

  6. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  7. Click Next.

  8. Optional: In the Resource adapters page, change the name of the adapter and add a description.

  9. Click OK.

  10. Click Save in the Messages box at the top of the page.


The next step is to export the module as an EAR file that you can deploy on the server.



Next topic: Export the module as an EAR file

Feedback


Export the module as an EAR file

Use IBM Integration Designer, export your module as an EAR file. By creating an EAR file, you capture all of the contents of your module in a format that can be easily deployed to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Before you can export a module as an EAR file, you must have created a module to communicate with your service. The module should be displayed in the IBM Integration Designer Business Integration perspective.

To export the module as an EAR file, perform the following procedure.

  1. Right-click the module and select Export.

  2. In the Select window, expand Java EE.

  3. Select EAR file and click Next.

  4. Optional: Select the correct EAR application. The EAR application is named after your module, but with "App" added to the end of the name.
  5. Browse for the folder on the local file system where the EAR file will be placed.

  6. To export the source files, select the Export source files check box. This option is provided in case you want to export the source files in addition to the EAR file. Source files include files associated with Javaâ„¢ components, data maps, and so on.

  7. To overwrite an existing file, click Overwrite existing file.

  8. Click Finish.

The contents of the module are exported as an EAR file.


Install the module in the administrative console. This deploys the module to IBM Business Process Manager or WebSphere Enterprise Service Bus.



Previous topic: Install the RAR file (for modules using stand-alone adapters only)


Next topic: Install the EAR file


Related tasks:

Install the EAR file

Feedback


Install the EAR file

Install the EAR file is the last step of the deployment process. When you install the EAR file on the server and run it, the adapter, which is embedded as part of the EAR file, runs as part of the installed application.

You must have exported your module as an EAR file before you can install it on IBM Business Process Manager or WebSphere Enterprise Service Bus.

To install the EAR file, perform the following procedure. For more information about clustering adapter module applications, see the http://www.ibm.com/software/webservers/appserv/was/library/.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > New Application > New Enterprise Application.

    Figure 1. Preparing for the application installation window

  5. Click Browse to locate your EAR file and click Next. The EAR file name is the name of the module followed by "App."

  6. If you are deploying to a clustered environment.

    1. On the Step 2: Map modules to servers window, select the module and click Next.

    2. Select the name of the server cluster.

    3. Click Apply.

  7. Click Next. In the Summary page, verify the settings and click Finish.

  8. If you are using an authentication alias:

    1. Expand Security and select Business Integration Security.

    2. Select the authentication alias to configure. You must have administrator or operator rights to change the authentication alias configurations.

    3. If it is not already specified, type the User name.

    4. If it is not already specified, type the Password.

    5. If it is not already specified, type the password again in the Confirm Password field.

    6. Click OK.

The project is now deployed and the Enterprise Applications window is displayed.


To set or reset any properties or you would like to cluster adapter project applications, make those changes using the administrative console before configuring troubleshooting tools.



Previous topic: Export the module as an EAR file


Related tasks:

Export the module as an EAR file

Feedback

Deploy the module in a clustered environment

In IBM Integration Designer, you can deploy the IBM WebSphere Adapter for FTP in a clustered environment.

To deploy the module in a clustered environment, use any of the following approaches.


Feedback


Deploy module embedded in the application

The adapter is deployed embedded in the application and specific to it. The adapter cannot be shared between multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the embedded adapter, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select With module for use by single application.

  2. Create the module as described in the Business process management samples for WebSphere Adapters.

  3. In the Dependencies option for the module, after the module is created, ensure the Deploy with module option is selected for the adapter.

  4. If the server is not running, right-click your server in the Servers view and select Start.
  5. When the server status changes to Started, right-click the server and select Administration > Run administrative console.

  6. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  7. On the Step 2: Map modules to servers window, select the module and click Next. For the embedded adapter option, the adapter is deployed as part of the application.

  8. In the Enterprise Applications view, select the new application <adapter_name>EmbeddedModuleApp. The new application is displayed after the application is deployed at the deployment manager level.

  9. Select the node and click Installed applications to view the deployed application on each individual node.

The resource adapter is embedded and deployed as part of the application.


Feedback


Deploy module at node level with embedded activation specification

The adapter is deployed at the node level, with the activation specification created during module creation. The adapter can be shared across multiple applications.

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use properties below.

  3. Create the module as described in the Business process management samples for WebSphere Adapters.

  4. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter. Here, the adapter is not part of the module, therefore you must deploy the adapter before deploying the application.

  5. If the server is not running, right-click your server in the Servers view and select Start.
  6. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  7. To deploy the adapter at individual nodes, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  8. In the Resource adapters page, click Install RAR.

  9. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  10. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  11. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  12. Click Save in the Messages box at the top of the page.

  13. For node level deployment, check if the adapter RAR is deployed at the node level.
  14. To deploy the adapter at the cluster level, click Resources > Resource Adapters > Resource adapters.

  15. In the Resource adapters window, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level.
  17. Check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  18. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  19. On the Step 2: Map modules to servers window, select the module and click Next. The adapter is not part of the deployed application.

  20. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for FTP > J2C activation specifications to view the activation specification from the adapter deployed at the cluster level.

The resource adapter is deployed at the node level, with the activation specification.


Feedback


Deploy module at node level with JNDI activation specification

The adapter is deployed at the node level, and the application provides a JNDI reference to the activation specification. Create the activation specification with the same JNDI name at the cluster scope from the administrative console. The adapter can be shared across multiple applications

The following steps are a necessary prerequisite to configure and deploy the module.

To create an application with the node level adapter and activation specification properties specified in the module itself, use the external service wizard.

  1. In the Service Configuration Properties window, from the Deploy connector project property list, select On server for use by multiple applications.

  2. From the Connection properties list, select Use JNDI lookup name configured on server.

  3. In the JNDI lookup name property field, specify the JNDI name. Use this same JNDI name when you create the activation specification from the Admin Console.

  4. Create the module as described in the Business process management samples for WebSphere Adapters.

  5. In the Dependencies option for the module, ensure the Deploy with module option is not selected for the adapter.

  6. If the server is not running, right-click your server in the Servers view and select Start.
  7. When the server status changes to Started, right-click the server and select Administration > Run administrative console. Log on to the administrative console.
  8. To install the adapter at the node level, click Resources > Resource Adapters > Resource adapters. In the clustered environment, install the adapter in each node separately.

  9. In the Resource adapters page, click Install RAR.

  10. In the Install RAR file page, click Browse and navigate to the RAR file for your adapter. Deploy the RAR on each node.

    The RAR files are typically installed in the following path: IID_installation_directory/ResourceAdapters/adapter_name/adapter.rar

  11. For deployment at node level, do not select any Scope because the scope is always Node. Click Next.

  12. Optional: In the Resource adapters page, change the name of the adapter and add a description. Click OK.

  13. Click Save in the Messages box at the top of the page.
  14. To install the RAR at the cluster level, click Resources > Resource Adapters > Resource adapters

  15. In the Resource adapters page, set the Scope to Cluster, and then click New.

  16. Select the RAR deployed at the node level, and then check if the adapter RAR is now deployed at the cluster level. Deploy the application after the adapter is deployed at the node level on the individual nodes, and then at the cluster level.

  17. From the Deployment Manager Admin Console, click Install applications to deploy the application.

  18. In the Admin Console, click Resources > Resource Adapters > IBM WebSphere Adapter for FTP > J2C activation specifications > New to create the activation specification from the adapter deployed at the cluster level.
  19. When installing the adapter, in the Name field, enter the same name as defined in the RAR.

  20. In the JNDI name field, enter the same name as given during the module creation.

  21. Click Resources > Resource Adapters > IBM WebSphere Adapter for FTP > J2C activation specifications to check if the JNDI reference on the adapter is same as the one specified for the module.

  22. Click Resources > Resource Adapters > IBM WebSphere Adapter for FTP > J2C activation specifications > Custom properties to set values for the activation specification in the Admin Console.

  23. From the Deployment Manager Admin console, click Install applications to deploy the application after you deploy the RAR and create the activation specification.

  24. On the Step 2: Map modules to servers page, select the module and click Next. The adapter is not part of the deployed application.

The resource adapter is deployed at the node level, with the JNDI activation specification reference.


Feedback


Administer the adapter module

When you are running the adapter in a stand-alone deployment, use the administrative console of the server to start, stop, monitor, and troubleshoot the adapter module. In an application that uses an embedded adapter, the adapter module starts or stops when the application is started or stopped.


Feedback


Configure logging and tracing

Configure logging and tracing to suit your requirements. Enable logging for the adapter to control the status of event processing. Change the adapter log and trace file names to separate them from other log and trace files.



Previous topic: Deploy the module for production


Next topic: Start the application that uses the adapter


Related tasks:

Troubleshooting and support

Feedback


Configure logging properties

Use the administrative console to enable logging and to set the output properties for a log, including the location, level of detail, and output format of the log. Before the adapters can log monitored events, you must specify the service component event points to monitor, what level of detail you require for each event, and format of the output used to publish the events to the logs. Use the administrative console to perform the following tasks:

For more information about monitoring on a Process Server, including service components and event points, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v7r5m1/topic/com.ibm.wbpm.admin.doc/topics/welcome_wps_mon.html.

You can change the log configuration statically or dynamically. Static configuration takes effect when you start or restart the application server. Dynamic or run time configuration changes apply immediately.

When a log is created, the detail level for that log is set from the configuration data. If no configuration data is available for a particular log name, the level for that log is obtained from the parent of the log. If no configuration data exists for the parent log, the parent of that log is checked, and so on, up the tree, until a log with a non-null level value is found. When you change the level of a log, the change is propagated to the child logs, which recursively propagate the change to their child log, as necessary.

To enable logging and set the output properties for a log, use the following procedure.

  1. In the navigation pane of the administrative console, select Servers > WebSphere application servers.

  2. Click the name of the server to work with.

  3. Under Troubleshooting, click Logging and tracing.

  4. Click Change log detail levels.

  5. Specify when you want the change to take effect:

    • For a static change to the configuration, click the Configuration tab.

    • For a dynamic change to the configuration, click the Runtime tab.

  6. Click the names of the packages whose logging level you want to modify. The package names for WebSphere Adapters start with com.ibm.j2ca.*:

    • For the adapter base component, select com.ibm.j2ca.base.*.

    • For the adapter base component and all deployed adapters, select com.ibm.j2ca.*.

    • For the WebSphere Adapter for FTP only, select the com.ibm.j2ca.ftp.* package.

  7. Select the logging level.

    >Logging Level >Description
    Fatal The task cannot continue or the component cannot function.
    Severe The task cannot continue, but the component can still function. This logging level also includes conditions that indicate an impending fatal error, that is, situations that strongly suggest that resources are on the verge of being depleted.
    Warning A potential error has occurred or a severe error is impending. This logging level also includes conditions that indicate a progressive failure, for example, the potential leaking of resources.
    Audit A significant event has occurred that affects the server state or resources.
    Info The task is running. This logging level includes general information outlining the overall progress of a task.
    Config The status of a configuration is reported or a configuration change has occurred.
    Detail The subtask is running. This logging level includes general information detailing the progress of a subtask.

  8. Click Apply.

  9. Click OK.

  10. To have static configuration changes take effect, stop and then restart the Process Server.

Log entries from this point forward contain the specified level of information for the selected adapter components.


Feedback


Change the log and trace file names

To keep the adapter log and trace information separate from other processes, use the administrative console to change the file names. By default, log and trace information for processes and applications on a Process Server is written to the SystemOut.log and trace.log files.

You can change the log and trace file names at any time after the adapter module has been deployed to an application server. You can change the log and trace file names statically or dynamically. Static changes take effect when you start or restart the application server. Dynamic or run time changes apply immediately.

Log and trace files are in the install_root/profiles/profile_name/logs/server_name folder.

To set or change the log and trace file names, use the following procedure.

  1. In the navigation pane of the administrative console, select Applications >Application Types>WebSphere enterprise applications.

  2. In the Enterprise Applications list, click the name of the adapter application. This is the name of the EAR file for the adapter, but without the ear file extension. For example, if the EAR file is named Accounting_OutboundApp.ear, then click Accounting_OutboundApp.

  3. In the Configuration tab, select Modules>Manage Modules.

  4. In the list of modules, click IBM WebSphere Adapter for FTP.

  5. In the Configuration tab, under Additional Properties, click Resource Adapter.

  6. In the Configuration tab, under Additional Properties, click Custom properties.

  7. In the Custom Properties table, change the file names.

    1. Click either logFilename to change the name of the log file or traceFilename to change the name of the trace file.

    2. In the Configuration tab, type the new name in the Value field. By default, the log file is called SystemOut.log and the trace file is called trace.log.

    3. Click Apply or OK. Your changes are saved on your local machine.
    4. To save your changes to the master configuration on the server, use one of the following procedures:

      • Static change: Stop and restart the server. This method allows you to make changes, but those changes do not take effect until you stop and start the server.
      • Dynamic change: Click the Save link in the Messages box above the Custom properties table. Click Save again when prompted.


Feedback


Change configuration properties for embedded adapters

To change the configuration properties after you deploy the adapter as part of a module, use the administrative console of the runtime environment. You can update resource adapter properties (used for general adapter operation), managed connection factory properties (used for outbound processing), and activation specification properties (used for inbound processing). For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.



Related reference:

Configuration properties

Feedback


Set resource adapter properties for embedded adapters

To set resource adapter properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change. The Configuration page is displayed.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for FTP.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click Custom properties.

  10. For each property you want to change.

    For more information about,

    1. Click the name of the property.

      The Configuration page for the selected property is displayed.

    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. In the Messages area, click Save.

The resource adapter properties associated with your adapter module are changed.



Related tasks:

Set managed (J2C) connection factory properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Resource adapter properties

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for embedded adapters

To set managed connection factory properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target FTP server instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. In the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for FTP.

  8. In the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C connection factories.

  10. Click the name of the connection factory associated with your adapter module.

  11. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to IBM WebSphere Adapter for FTP. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  12. For each property you want to change.

    See Managed (J2C) connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The managed connection factory properties associated with your adapter module are changed.



Related tasks:

Set resource adapter properties for embedded adapters

Set activation specification properties for embedded adapters


Related reference:

Managed (J2C) connection factory properties

Feedback


Set activation specification properties for embedded adapters

To set activation specification properties for your adapter after it has been deployed as part of a module, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter module must be deployed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Select Applications > Application Types > WebSphere enterprise application.

  5. From the Enterprise Applications list, click the name of the adapter module whose properties you want to change.

    Figure 1. The Manage Modules selection in the Configuration tab

  6. Under Modules, click Manage Modules.

  7. Click IBM WebSphere Adapter for FTP.

  8. From the Additional Properties list, click Resource Adapter.

  9. On the next page, from the Additional Properties list, click J2C activation specifications.

  10. Click the name of the activation specification associated with the adapter module.

  11. From the Additional Properties list, click J2C activation specification custom properties.

  12. For each property you want to change.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  13. In the Messages area, click Save.

The activation specification properties associated with your adapter module are changed.

If the changes are not reflected even after you have restarted the application, restart the server so the changes are reflected.



Related tasks:

Set resource adapter properties for embedded adapters

Set managed (J2C) connection factory properties for embedded adapters


Related reference:

Activation specification properties

Feedback


Change configuration properties for stand-alone adapters

To set configuration properties after you install a stand-alone adapter, use the administrative console of the runtime environment. Provide the general information about the adapter and then set the resource adapter properties (which are used for general adapter operation). If the adapter is used for outbound operations, create a connection factory and then set the properties for it. If the adapter is used for inbound operations, create an activation specification and then set the properties for it. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.


Feedback


Set resource adapter properties for stand-alone adapters

To set resource adapter properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

Custom properties are default configuration properties shared by all IBM WebSphere Adapters.

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for FTP.

  6. In the Additional Properties list, click Custom properties.

  7. For each property you want to change.

    For more information about,

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  8. In the Messages area, click Save.

The resource adapter properties associated with your adapter are changed.



Related reference:

Resource adapter properties

Resource adapter properties

Feedback


Set managed (J2C) connection factory properties for stand-alone adapters

To set managed connection factory properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the property you want to configure and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use managed connection factory properties to configure the target FTP server instance.

In the administrative console, the properties are referred to as "J2C connection factory properties."

To configure properties using the administrative console, use the following procedure:

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for FTP.

  6. In the Additional Properties list, click J2C connection factories.

  7. To use an existing connection factory, skip ahead to select from the list of existing connection factories.

    If you have selected Specify connection properties when use the external service wizard to configure the adapter module, you do not need to create a connection factory.

    If you are creating a connection factory, perform the following steps:

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the connection factory. For example, you can type AdapterCF.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterCF.

    4. Optional: Select an authentication alias from the Component-managed authentication alias list.

    5. Click OK.

    6. In the Messages area, click Save.

      The newly created connection factory is displayed.

      Figure 1. User-defined connection factories for use with the resource adapter

  8. In the list of connection factories, click the one you want to use.

  9. In the Additional Properties list, click Custom properties.

    Custom properties are those J2C connection factory properties that are unique to WebSphere Adapter for FTP. Connection pool and advanced connection factory properties are properties you configure if you are developing your own adapter.

  10. For each property you want to change.

    See Managed (J2C) connection factory properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The managed connection factory properties associated with your adapter are set.



Related reference:

Managed (J2C) connection factory properties

Feedback


Set activation specification properties for stand-alone adapters

To set activation specification properties for your stand-alone adapter after it has been installed on IBM Business Process Manager or WebSphere Enterprise Service Bus, use the administrative console. You select the name of the message endpoint property you want to configure, and then change or set the value.

Your adapter must be installed on IBM Business Process Manager or WebSphere Enterprise Service Bus.

You use activation specification properties to configure the endpoint for inbound processing.

To configure properties using the administrative console, use the following procedure.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Resources > Resource Adapters > Resource adapters.

  5. In the Resource adapters page, click IBM WebSphere Adapter for FTP.

  6. In the Additional Properties list, click J2C activation specifications.

  7. To use an existing activation specification, skip ahead to select from an existing list of activation specifications.

    If you have selected Use predefined connection properties when use the external service wizard to configure the adapter module, create an activation specification.

    If you are creating an activation specification.

    1. Click New.

    2. In the General Properties section of the Configuration tab, type a name for the activation specification. For example, you can type AdapterAS.
    3. Type a value for JNDI name. For example, you can type com/eis/AdapterAS.

    4. Optional: Select an authentication alias from the Authentication alias list.

    5. Select a message listener type.

    6. Click OK.

    7. Click Save in the Messages box at the top of the page.

      The newly created activation specification is displayed.

  8. In the list of activation specifications, click the one you want to use.

  9. In the Additional Properties list, click J2C activation specification custom properties.

  10. For each property you want to set.

    See Activation specification properties for more information about these properties.

    1. Click the name of the property.
    2. Change the contents of the Value field or type a value, if the field is empty.

    3. Click OK.

  11. After you have finished setting properties, click Apply.

  12. In the Messages area, click Save.

The activation specification properties associated with your adapter are set.

If the changes are not reflected even after you have restarted the application, restart the server so the changes are reflected.



Related reference:

Activation specification properties

Feedback


Start the application that uses the adapter

Use the administrative console of the server to start an application that uses the adapter. By default, the application starts automatically when the server starts.

Use this procedure to start the application, whether it is using an embedded or a stand-alone adapter. For an application that uses an embedded adapter, the adapter starts when the application starts. For an application that uses a stand-alone adapter, the adapter starts when the application server starts.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to start. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Start.

The status of the application changes to Started, and a message stating the application has started displays at the top of the administrative console.



Previous topic: Configure logging and tracing


Related tasks:

Stop the application that uses the adapter

Feedback


Stop the application that uses the adapter

Use the administrative console of the server to stop an application that uses the adapter. By default, the application stops automatically when the server stops.

Use this procedure to stop the application, whether it is using an embedded or a stand-alone adapter. For an application with an embedded adapter, the adapter stops when the application stops. For an application that uses a stand-alone adapter, the adapter stops when the application server stops.

  1. If the server is not running, right-click your server in the Servers view and select Start.
  2. When the server status changes to Started, right-click the server and select Administration > Run administrative console.
  3. Log on to the administrative console.

  4. Click Applications > Application Types > WebSphere enterprise applications.

    The administrative console is labeled "Integrated Solutions Console".

  5. Select the application to stop. The application name is the name of the EAR file you installed, without the .EAR file extension.

  6. Click Stop.

The status of the application changes to Stopped, and a message stating the application has stopped is displayed at the top of the administrative console.



Related tasks:

Start the application that uses the adapter

Feedback


Monitor performance using Performance Monitoring Infrastructure

Performance Monitoring Infrastructure (PMI) is a feature of the administrative console that allows you to dynamically monitor the performance of components in the production environment, including IBM WebSphere Adapter for FTP. PMI collects adapter performance data, such as average response time and total number of requests, from various components in the server and organizes the data into a tree structure. You can view the data through the Tivoli Performance Viewer, a graphical monitoring tool that is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus. You can monitor the performance of your adapter by having PMI collect data at the following points:

Before you enable and configure PMI for your adapter, you must first set the level of tracing detail and run some events from which to gather performance data.

To learn more about how PMI can help you monitor and improve the overall performance of your adapter environment, search for PMI on the BPM or WebSphere Enterprise Service Bus website: http://www.ibm.com/software/webservers/appserv/was/library/.

  1. Configure Performance Monitoring Infrastructure You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.
  2. Enable tracing with the Common Event Infrastructure The adapter can use the Common Event Infrastructure (CEI), a component embedded in the server, to report data about critical business events such as the starting or stopping of a poll cycle. Event data can be written to a database or a trace log file depending on configuration settings.
  3. View performance statistics You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.


Feedback


Configure Performance Monitoring Infrastructure

You can configure Performance Monitoring Infrastructure (PMI) to gather adapter performance data, such as average response time and total number of requests. After you configure PMI for your adapter, you can monitor the adapter performance using Tivoli Performance viewer.

Before you can configure PMI for your adapter, you must first set the level of tracing detail and run some events to gather the performance data.

  1. To enable tracing and to receive event data, the trace level must be set to either fine, finer, finest, or all. After *=info, add a colon and a string, for example: 
    *=info: WBILocationMonitor.CEI.ResourceAdapter.
*=finest: WBILocationMonitor.LOG.ResourceAdapter.*=finest:
    For instructions on setting the trace level, see Enable tracing with the Common Event Infrastructure.
  2. Generate at least one outbound request or inbound event to produce performance data that you can configure.

  1. Enable PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select the Configuration tab, and then select the Enable Performance Monitoring (PMI) check box.

    4. Select Custom to selectively enable or disable statistics.

      Figure 1. Enabling Performance Monitoring Infrastructure

    5. Click Apply or OK.

    6. Click Save. PMI is now enabled.

  2. Configure PMI for your adapter.

    1. In the administrative console, expand Monitoring and Tuning, and then select Performance Monitoring Infrastructure (PMI).

    2. From the list of servers, click the name of your server.

    3. Select Custom.

    4. Select the Runtime tab. The following figure shows the Runtime tab.

      Figure 2. Runtime tab used for configuring PMI

    5. Click WBIStats.RootGroup. This is a PMI sub module for data collected in the root group. This example uses the name WBIStats for the root group.

    6. Click ResourceAdapter. This is a sub module for the data collected for the JCA adapters.

    7. Click the name of your adapter, and select the processes you want to monitor.

    8. In the right pane, select the check boxes for the statistics you want to gather, and then click Enable.

PMI is configured for your adapter.


Now you can view the performance statistics for your adapter.



Next topic: Enable tracing with the Common Event Infrastructure

Feedback


Enable tracing with the Common Event Infrastructure

The adapter can use the Common Event Infrastructure (CEI), a component embedded in the server, to report data about critical business events such as the starting or stopping of a poll cycle. Event data can be written to a database or a trace log file depending on configuration settings.

Use this procedure to report CEI entries in the trace log file by using the Common Base Event Browser within the administrative console.

  1. In the administrative console, click Troubleshooting.

  2. Click Logs and Trace.

  3. From the list of servers, click the name of your server.

  4. In the Change Log Detail Levels box, click the name of the CEI database ( WBIEventMonitor.CEI.ResourceAdapter.*) or the trace log file ( WBIEventMonitor.LOG.ResourceAdapter.*) to which you want the adapter to write event data.

  5. Select the level of detail about business events that you want the adapter to write to the database or trace log file, and (optionally) adjust the granularity of detail associated with messages and traces.

    • No Logging. Turns off event logging.
    • Messages Only. The adapter reports an event.
    • All Messages and Traces. The adapter reports details about an event.
    • Message and Trace Levels. Settings for controlling the degree of detail the adapter reports about the business object payload associated with an event. To create adjust the detail level, select one of the following options:

      Fine. The adapter reports the event but none of the business object payload.

      Finer. The adapter reports the event and the business object payload description.

      Finest. The adapter reports the event and the entire business object payload.

  6. Click OK.

Event logging is enabled. You can view CEI entries in the trace log file or by using the Common Base Event Browser within the administrative console.



Previous topic: Configure Performance Monitoring Infrastructure


Next topic: View performance statistics

Feedback Infrastructure (PMI), Tivoli Performance Viewer, IBM WebSphere Adapter for FTP


View performance statistics

You can view adapter performance data through the graphical monitoring tool, Tivoli Performance Viewer. Tivoli Performance Viewer is integrated with the administrative console in BPM or WebSphere Enterprise Service Bus.

Configure Performance Monitoring Infrastructure for your adapter.

  1. In the administrative console, expand Monitoring and Tuning, expand Performance Viewer, then select Current Activity.

  2. In the list of servers, click the name of your server.

  3. Under your server name, expand Performance Modules.

  4. Click WBIStatsRootGroup.

  5. Click ResourceAdapter and the name of your adapter module.

  6. If there is more than one process, select the check boxes for the processes whose statistics you want to view.

The statistics are displayed in the right panel. You can click View Graph to view a graph of the data, or View Table to see the statistics in a table format.

The following figure shows adapter performance statistics.

Figure 1. Adapter performance statistics, using graph view



Previous topic: Enable tracing with the Common Event Infrastructure

Feedback


10. Troubleshooting and support

Common troubleshooting techniques and self-help information help you identify and solve problems quickly. For information about configuring logging properties and changing the log and trace file names, see Configure logging and tracing.



Related concepts:

Resume file transfer


Related tasks:

Configure logging and tracing


Related reference:

Messages

Feedback


Techniques for troubleshooting problems

Certain common techniques can help with the task of troubleshooting.

The first step in the troubleshooting process is to describe the problem completely. Without a problem description, neither you or IBM can know where to start to find the cause of the problem. This step includes asking yourself basic questions, such as:

The answers to these questions typically lead to a good description of the problem, and that is the best way to start down the path of problem resolution.


What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is the problem?" Which might seem like a straightforward question; however, you can break it down into several more-focused questions that create a more descriptive picture of the problem. These questions can include:


Where does the problem occur?

Determining where the problem originates is not always simple, but it is one of the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only a few components to be considered when you are investigating problems.

The following questions can help you to focus on where the problem occurs in order to isolate the problem layer.

Remember that if one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration; many problems can be traced back to incompatible levels of software not intended to run together or have not been fully tested together.


When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for those cases that are one-time occurrences. You can most simply do this by working backward: Start at the time an error was reported (as precisely as possible, even down to the millisecond), and work backward through the available logs and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic log; however, this is not always simple to do and takes practice. Knowing when to stop looking is especially difficult when multiple layers of technology are involved, and when each has its own diagnostic information.

To develop a detailed timeline of events, answer the following questions:

Responding to these types of questions can provide you with a frame of reference in which to investigate the problem.


Under which conditions does the problem occur?

Knowing what other systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These and other questions about the environment can help you to identify the root cause of the problem:

Answering these types of questions can help you explain the environment in which the problem occurs and correlate any dependencies. Remember that just because multiple problems might have occurred around the same time, the problems are not necessarily related.


Can the problem be reproduced?

From a troubleshooting standpoint, the "ideal" problem is one that can be reproduced. Typically with problems that can be reproduced, you have a larger set of tools or procedures at your disposal to help you investigate. Consequently, problems that you can reproduce are often simpler to debug and solve. However, problems that you can reproduce can have a disadvantage: If the problem is of significant business impact, you do not want it to recur! If possible, re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation.

Tip: Simplify the scenario to isolate the problem to a suspected component.

The following questions can help you with reproducing the problem:


Feedback


ServerToServerFileTransfer

The specified file is transferred from one FTP server directory to another FTP server directory.

If the value of the host name property is set to localhost, the first server is located on the same system as the adapter workstation. The adapter generates the following error: 421 error-Can't open data connection. To work around this problem, edit the hosts file (which, for the Windows platform, is located at <WindowsHome>/system32/drivers/etc/hosts) and add a new entry with the external IP address, for example, 9.186.116.151 localhost.

The adapter will also work if the host name value or the external IP address is used for example, if FTPTEST is used as the host name format or 9.186.116.151 is used as the IP format.


Feedback


Resume file transfer

If the connection to the FTP server breaks during the transfer of a file, the transfer can be resumed from the point at which it was interrupted.

Problem

If there are network-related issues when a file transfer is in progress for an outbound create operation, it is observed that some of the FTP servers retain reference to the connection at the server end and does not close the reference when the connection is broken. Hence, an error occurs when the outbound request is resent to resume the transfer of the file. The FTP server returns a reply code "550 Can't access file" when the outbound create request is resent. This is due to the file lock in the target file maintained by the connection reference created at the FTP server during the previously failed file transfer request.

Solution

The invalid connection handle must be cleared from the FTP server manually for the outbound request to resume transfer of the file. If 'connection timeout' or 'No-transfer timeout' related properties are set at the FTP server, the invalid connection handle is cleared upon exceeding the timeout interval and any subsequent outbound request to resume the file transfer is successful.



Related tasks:

Troubleshooting and support

Feedback


Processing files in the mapped local event directory

Symptom

In a clustered environment, where the nodes are running on different machines, the files in the mapped local event directory might not be processed completely or correctly. This issue might occur during both inbound and outbound operations.

Problem

In the Windows operating systems, such as, Windows 7, Windows Vista, and Windows Server 2008, there are issues faced in the mapped drive connection.

Solution

To resolve the issues with the mapped drives, refer to articles on mapped drive connection to network sharing, for your operating system.


Feedback


Adapter not connecting to FTP server

Problem

During inbound processing, the adapter is not connecting to FTP server correctly.

Cause

If the dataConnectionMode property is not set based on the firewall settings for the FTP server and the adapter, the adapter does not connect to FTP server.

Solution

If the adapter is behind the firewall, set the dataConnectionMode property value as passive. If the FTP server is behind the firewall, set the dataConnectionMode property value as active.


Feedback


Changes to runtime properties not reflected at run time

Problem

Any changes that are made to the activation specification and the interaction specification properties in the administrative console are not reflected at run time.

While deploying the adapter, you must restart the application for the changes to be reflected. There are some instances where these changes are not reflected, even after you restart the application.

Solution

If the changes are not reflected even after you have restarted the application, restart the server so the changes are reflected.


Feedback


Adapter returns version conflict exception message


Adapter returns version conflict exception message

Problem

When you install multiple adapters with different versions of CWYBS_AdapterFoundation.jar, and if a lower version of the CWYBS_AdapterFoundation.jar is loaded during run time, the adapter returns the ResourceAdapterInternalException error message, due to a version conflict. For example, when you install Oracle E-Business Suite adapter version 7.0.0.3 and WebSphere Adapter for FTP version 7.5.0.3, the following error message is displayed "The version of CWYBS_AdapterFoundation.jar is not compatible with IBM WebSphere Adapter for FTP" as IBM WebSphere Adapter for FTP loads file:/C:/IBM/WebSphere/ProcServer7/profiles/ProcSrv01/installedConnectors/CWYOE_OracleEBS.rar/CWYBS_AdapterFoundation.jar with version 7.0.0.3. However, the base level of this jar required is version 7.5.0.3.

Solution

Migrate all adapters to the same version level.

For further assistance, visit http://www.ibm.com/support/docview.wss?uid=swg27006249.


Feedback


Outbound operation fails at folder level

Problem

During outbound processing, all outbound operations fail when they are performed at a folder level.

Cause

Outbound operations are supported only for files, and not for folders.

Solution

Adapter for FTP is not supported for folders. To perform any operation on folders, use the ExecuteFtpScript outbound operation.


Feedback


Disable end point applications of the passive adapter

Problem

In the active-passive configuration mode of the adapters, the endpoint application of the passive adapter instance also listens to the events or messages even if the enableHASupport property is set to True.

Cause

By default, in WebSphere Application Server, the alwaysactivateAllMDBs property in the JMS activation specification is set to True. This enables the endpoint application of all the adapter (active or passive) instances to listen to the events.

Solution

To stop the endpoint application of the passive adapter instance from listening to the events, you must set the alwaysactivateAllMDBs property value to False. The JMS activation specification is associated with one or more MDBs and provides the necessary configuration to receive events. If the alwaysActivateAllMDBs property is set to False, then the endpoint application of only the active adapter instance receives the events.

Perform the following procedure, to set the alwaysActivateAllMDBs property to False.

  1. Log on to the administrative console.
  2. Go to Resources> JMS > Activation specifications.

  3. Click the activation specification corresponding to the application from the list.

  4. Click Custom properties under Additional properties.

  5. Click alwaysActivateAllMDBs.
  6. Change the value to False.

  7. Click Apply and OK.

Result

The endpoint application of only the active adapter instance listens to the events.


Feedback


Out of memory exception error


Out of memory exception error while polling large-size files during inbound processing

Problem

During inbound polling, the adapter fails to poll large-size files and generates an out of memory exception error.

Solution

If you split an event file by size, ensure the SplitCriteria property contains a valid chunk value. A non-negative integer is considered as a valid chunk. If the value in the SplitCriteria property is not configured, the whole file is processed as a single business object and can throw exceptions with large-size files. When you specify the split size value, the file is processed in split sized chunks resulting in a successful poll. For more information about the splitting of files, see Splitting files.


Out of memory exception error while retrieving large-size files during outbound processing

Problem

When retrieving content for large-size files during the retrieve operation, the adapter generates an out of memory exception error.

Solution

If an out of memory exception error is generated, it indicates the machine configuration does not support processing of large-size files. For more information about the retrieve operation, see Supported operations.


Feedback


Known issues in editing the Rule Table

When configuring the adapter to filter event files based on a set of rules, some known issues can occur while editing the Rule Table in the Properties view. To correct the problem follow the solutions described here for each of these issues.

Symptoms

When an existing Rule Table row is configured in the Properties view, the following issue can occur:

Problem

After you have completed entering all the required properties, the Finish option is not enabled for you to complete the editing of the Rule Table.

Solution

To correct this problem, use either of the following workaround:



Related tasks:

Set deployment and runtime properties


Related reference:

Activation specification properties

Feedback


Support for global elements without wrapper

When global element without wrapper is used as input type, you need to take care of using the correct configuration described for the below listed scenarios to get the expected result.


Global element of named type without wrapper during outbound processing

When global element of named type without wrapper is used as input type in adapter outbound using UTF8XML Datahandler, the file is serialized with global element type name as root element name, instead of the global element name.

To serialize file to get the global element name as the root element name, you need to use the XML Datahandler and specify the global element name as the root element name in XML datahandler configuration.


Global element of anonymous type without wrapper

When global element of anonymous type without wrapper is used as input type in adapter inbound or outbound retrieve, the data object is emitted back to SCA component. When this data object is serialized, it returns the type name of dataobject as ‘globalelementname_._type'.

To get the correct data object type, in order to be used for a global element of anonymous type without wrapper, for inbound as well as outbound retrieve, you need to use the following code snippet. 

The following sample code can be used to get the correct
dataobject details for global element of anonymous type without wrapper, which is named as GlobalElementExample1.

import java.io.ByteArrayOutputStream;
import java.io.IOException;

import commonj.sdo.DataObject;
import commonj.sdo.Type;

import com.ibm.websphere.bo.BOFactory;
import com.ibm.websphere.bo.BOXMLSerializer;
import com.ibm.websphere.sca.ServiceManager;

public void emit(DataObject globalElementExample1) {
ServiceManager s = ServiceManager.INSTANCE;
BOFactory factory= (BOFactory) s.locateService
("com/ibm/websphere/bo/BOFactory");
DataObject dobj= factory.createByElement
(globalElementExample1.getType().getURI(), "GlobalElementExample1");
final Type type = dobj.getType();
String typeName = type.getName();
if (typeName.endsWith("_._type"))
         typeName = typeName.substring(0, typeName.indexOf("_._type"));
BOXMLSerializer serializer = BOXMLSerializer)s.locateService
("com/ibm/websphere/bo/BOXMLSerializer");
ByteArrayOutputStream baos = new ByteArrayOutputStream();
serializer.writeDataObject(globalElementExample1, type.getURI(), typeName, baos);
String bo = new String(baos.toByteArray());
System.out.println("bo : "+bo);}


Feedback


Global elements in SDOX mode throw exceptions

In SDOX (Service Data Objects - XML Cursor Interface) mode, the adapter throws the DataBindingException or IllegalArgumentException exception when the global element feature is used in the business object structure.


DataBindingException when using anonymous complex type global element

The adapter throws a DataBindingException exception when running in SDOX mode during the outbound operations, if it uses the following settings:

The exception can occur when running the Create, Append, Overwrite, or Retrieve outbound operation.

The stack trace of WebSphere Adapter for FTP contains a trace report. An example of a trace report is shown here. 

[12/3/09 10:26:00:156 CST] 00000058 FfdcProvider I com.ibm.ws.ffdc.impl.FfdcProvider
 logIncident FFDC1003I: FFDC Incident emitted on C:\W7\profiles\ProcSrv01\logs\ffdc\server1_71327132_09.12.03_10.26.00.1404512422641450978700.
txt com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding
 getBiDiContext[12/3/09 10:26:00:156 CST] 00000058 FfdcProvider I com.ibm.ws.ffdc.impl.FfdcProvider
 logIncident FFDC1003I: FFDC Incident emitted on C:\W7\profiles\ProcSrv01\logs\ffdc\server1_71327132_09.12.03_10.26.00.1564220276222456620949.
txt com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding
 getRecord[12/3/09 10:26:00:156 CST] 00000058
FFRADB E Error on getRecord(): commonj.connector.runtime.DataBindingException:
Error while bidi format at
com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding.getBiDiContext
(FTPBaseDataBinding.java:1083)
at com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding.getRecord
(FTPBaseDataBinding.java:134)

To correct the problem, while using anonymous complex type global element for outbound operations, use the BOWrapper instead of business object as the data type.


IllegalArgumentException during the outbound operations

The adapter throws a IllegalArgumentException exception when running in SDOX mode during the outbound operations, if it uses the following settings:

The exception can occur when running the Create, Append, Overwrite, or Retrieve outbound operation. The stack trace of WebSphere Adapter for FTP contains a trace report. An example of a trace report is shown here. 

[12/8/09 18:22:00:906 CST] FFDC Exception:java.lang.IllegalArgumentException SourceId:com.ibm.j2ca.
ftp.emd.runtime.FTPBaseDataBinding ProbeId:getRecord Reporter:java.lang.Class@61e461e4
java.lang.IllegalArgumentException: Expected a DataObject GlobalElementExample1Wrapper
inside GlobalElementExample1WrapperBG but found none.
at com.ibm.j2ca.extension.emd.runtime.internal.DataBindingUtil.getBOFromBG(DataBindingUtil.java:459)
at com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding.getContentObject
(FTPBaseDataBinding.java:640)
at com.ibm.j2ca.ftp.emd.runtime.
FTPBaseDataBinding.getRecord
(FTPBaseDataBinding.java:118)
at com.ibm.ws.sca.binding.j2c.J2CMethodBindingImpl.invoke(J2CMethodBindingImpl.java:1202)
at com.ibm.ws.sca.binding.j2c.J2CInterfaceBindingImpl.invoke(J2CInterfaceBindingImpl.java:152)
at com.ibm.ws.sca.binding.j2c.handler.J2CImportHandler.invokeDynamicImport(J2CImportHandler.java:1314)

To correct the problem, use either of the following workaround:


Feedback


First-failure data capture (FFDC) support

The adapter supports first-failure data capture (FFDC), which provides persistent records of failures and significant software incidents that occur during run time in BPM or WebSphere Enterprise Service Bus.

The FFDC feature runs in the background and collects events and errors that occur at run time. The feature provides a means for associating failures to one another, allowing software to link the effects of a failure to their causes, and facilitate the quick location of the root cause of a failure. The data that is captured can be used to identify exception processing that occurred during the adapter run time.

When a problem occurs, the adapter writes exception messages and context data to a log file, which is in the install_root/profiles/profile/logs/ffdc directory.

For more information about first-failure data capture (FFDC), see the BPM or WebSphere Enterprise Service Bus documentation.


Feedback


Unable to invoke adapter through webservices

Problem

After configuring the adapter, you might note that:

  1. the webservices client based on the WSDL is not getting generated properly in IBM Integration Designer.
  2. you may not be able to invoke the WSDL using certain webservices client, such as RESTUI firefox plugin and soapUI tool.

Solution

Perform the following steps to enable the adapter module to load the ASI file.

  1. Create a library project.
  2. Change to the Enterprise Explorer view in IBM Integration Designer.

  3. Locate the ASI file of the adapter in connector project -> connectorModule.
  4. Copy the ASI file of the adapter and paste it in the library project.

  5. Add the library project to the list of dependencies for the adapter module.
  6. Clean project.


Feedback


Adapter fails during inbound processing

Problem

During inbound processing, the adapter fails to connect to the FTP server and stops polling for events.

Cause

During inbound processing, there is a delay in response by one command from the FTP server.

For example, command1 does not receive any response for the command sent to FTP server, but the next command, that is, command2 receives this response sent from the FTP server to command1. Because of this delay in responding to commands, the adapter never receives the correct response and fails to further process the events.

Solution

Verify the FTP server administration settings.


Feedback


Adapter not applying the file mask during recovery

Problem

When two adapters use the same local event directory with different file masks, the adapters individually process the files from the directory. However, when you restart one of the adapters, it picks up the files intended for another adapter using the same local event directory.

Cause

As per the design, the adapter applies the file mask only when picking the files for processing and not during the restart or recovery.

Solution

IBM recommends that each adapter should have its own unique local event directory. This ensures the adapter will apply the file masks during the restart or recovery also.

However, In a HA Active-Active configuration, multiple adapters can share the same local event directory.


Feedback


org.xml.sax.SAXParseException

When the adapter is configured with the XML data handler, an org.xml.sax.SAXParseException exception is generated if the content is not in the specified business object format. To correct the problem, make sure the file content matches the business object structure. If the file contains multiple business objects, make sure the delimiter is specified correctly.

Symptom

When the adapter is configured with the XML data handler, the following exception is thrown:

Problem

The content of the file is not in the specified business object format.

Solution

To correct this problem, use the following procedure:

  1. Verify the file content matches the business object structure.
  2. If the content file contains multiple business objects, make sure the delimiter is specified correctly.


Feedback


Frequently Asked Questions

Answers to a set of frequently asked questions about WebSphere Adapter for FTP.


How to configure a local event directory and a sequence file in a clustered environment?


How to make the file listing of FTP sever (ls –l) compatible with the adapter?

Ensure the FTP server is set to provide responses in UNIX format so the adapter can parse them.


What are the pre-requisites for the adapter to work properly?

For the adapter to communicate with the FTP server and work properly, ensure the following settings are configured.


How to check for access permissions in an output, remote event, or remote archive directory?

To check if the userID the adapter uses has the right access permissions to access the FTP server, the adapter performs the following actions:


What is HA Active-Active and Active-Passive configuration?

WebSphere adapter supports High Availability (HA) Active-Active configuration during inbound processing in a clustered environment.

An HA Active-Active configuration,

In a HA Active-Passive configuration,


Feedback

Support

This section provides information about how to troubleshoot a problem with your IBM software, including instructions for searching knowledge bases, downloading fixes, and obtaining support.


Feedback


Searching knowledge bases (Web search)

You can often find solutions to problems by searching IBM knowledge bases. You can optimize your results by using available resources, support tools, and search methods.

You can find useful information by searching the information center for Product X. However, sometimes you need to look beyond the information center to answer your questions or resolve problems.

To search knowledge bases for information that you need, use one or more of the following approaches:

Tip: Include "IBM" and the name of the product in your search if you are looking for information about an IBM product.


Feedback


Getting Fixes

A product fix might be available to resolve your problem.

To get product fixes.

  1. Determine which fix you need. Check the list of IBM WebSphere Adapter for FTP recommended fixes to confirm that your software is at the latest maintenance level. Check the list of problems fixed in the IBM WebSphere Adapter for FTP fix readme documentation that is available for each listed fix pack to see if IBM has already published an individual fix to resolve your problem. To determine what fixes are available using IBM Support Assistant, run a query on fix from the search page.

    Individual fixes are published as often as necessary to resolve defects in BPM or WebSphere Enterprise Service Bus IBM WebSphere Adapter for FTP. In addition, two kinds of cumulative collections of fixes, called fix packs and refresh packs, are published periodically for IBM WebSphere Adapter for FTP, in order to bring users up to the latest maintenance level. You should install these update packages as early as possible in order to prevent problems.

    A list of recommended, generally available (GA) fixes for the WebSphere Javaâ„¢ Connector Architecture (JCA) and WebSphere Business Integration adapters are available here. If a Fix Pack is not available for an adapter, it implies the GA version is the recommended version and details about that version of the adapter can be found in the Release notes.

  2. Download the fix. Open the download document and follow the link in the Download package section. When downloading the file, ensure the name of the maintenance file is not changed. This includes both intentional changes and inadvertent changes caused by certain web browsers or download utilities.
  3. Apply the fix. Follow the instructions in the Installation Instructions section of the download document.

  4. To receive weekly notification of fixes and updates, subscribe to My Support e-mail updates.


Feedback


Self-help resources

Use the resources of IBM software support to get the most current support information, obtain technical documentation, download support tools and fixes, and avoid problems with WebSphere Adapters. The self-help resources also help you diagnose problems with the adapter and provide information about how to contact IBM software support.


Support website

The WebSphere Adapters software support website at http://www.ibm.com/support/docview.wss?uid=swg27006249 provides links to many resources to help you learn about, use, and troubleshoot WebSphere Adapters, including:


Recommended fixes

A list of recommended fixes apply is available at the following location: http://www.ibm.com/support/docview.wss?fdoc=aimadp&rs=695&uid=swg27010397.


Technotes

Technotes provide the most current documentation about WebSphere Adapter for FTP, including the following topics:

For a list of technotes for WebSphere Adapter for FTP, see http://www-01.ibm.com/support/docview.wss?uid=swg27024026.

For a list of technotes for all adapters, see http://www.ibm.com/support/search.wss?tc=SSMKUK&rs=695&rank=8&dc=DB520+D800+D900+DA900+DA800+DB560&dtm.


Feedback


11. Reference information

To support you in your tasks, reference information includes details about business objects that are generated by the external service wizard and information about adapter properties, including those that support bidirectional transformation. It also includes pointers to adapter messages and related product information.


Feedback


Business object information

You can determine the purpose of a business object by examining both the application-specific information within the business object definition file and the name of the business object. The application-specific information dictates what operations can be performed on the FTP server. The name typically reflects the operation to be performed and the structure of the business object.


Feedback


Business object structure

The adapter supports three different types of business object structures. A generic business object, which is used to pass unstructured data. A generic business object with a business graph, which contains the action to be performed on the data and the connection-specific information. A user-defined type, which is a content-specific business object that supports specific business object structures (such as customer and order business objects).

Business graphs are optional and can be selected in the external service wizard.

The FTPFileBG, FTPFile, and UnstructuredContent generic business object definitions are automatically generated. Depending on the custom complex types selected when you create external services, the corresponding business object or objects definitions are also generated. For example, if you select Customer, including the optional business graph, the CustomerWrapperBG and CustomerWrapper business objects are generated.


FTPFileBG

The FTPFileBG business object is a generic business object that contains the verb (the action to be performed on the data) and the FTPFile business object as a child. The following graphic illustrates this relationship.

Figure 1. FTPFileBG business object


FTPFile

The FTPFile business object contains all necessary connection information, and an UnstructuredContent business object as a child. The following graphic illustrates this relationship.

Figure 2. FTPFile business object


CustomerWrapperBG

The CustomerWrapperBG is a business object that contains the verb (the action to be performed on the data) and the CustomerWrapper business object as a child. The following graphic illustrates this relationship.

Figure 3. CustomerWrapperBG business object


CustomerWrapper

The CustomerWrapper business object is a business object that contains all necessary connection information and the content-specific Customer business object as a child. The following graphic illustrates this relationship.

Figure 4. CustomerWrapper business object


Global elements in a structured business object

The WebSphere Adapter for FTP supports global elements in structured business objects. Global elements with null namespace are also supported.

Figure 5. Structure of the global elements in a structured Business Object

The CustomerType1 is the global element in the business object.

The CustomerInventory is the global element in the business object.


Feedback


Naming conventions

When the external service wizard generates a business object, it provides a name for the business object based on the name of the object in the FTP server that it uses to build the business object. Use the Business Object Editor to user-defined objects.

external service wizard converts the name of the object to mixed case. The separators, such as spaces or underscores, are removed. Then, the first letter of each word is capitalized. For example, if the external service wizard uses an FTP server object called CUSTOMER_ADDRESS to generate a business object, it generates a business object called CustomerAddress.

The generated business object name can indicate the structure of the business object. However, the business object's name has no semantic value to the adapter. If you change the business object name, the behavior of the business object remains the same.

If you choose to rename a business object, use the refactoring functionality in IBM Integration Designer to ensure that you update all the business object dependencies. For instructions about the refactoring functionality to rename business objects, see http://publib.boulder.ibm.com/infocenter/dmndhelp/v8r0mx/topic/com.ibm.wbpm.wid.bpel.doc/selector/topics/trefacts.html .

Business graph generation is optional and is supported for BPM only.


Feedback


Support for null namespace

WebSphere Adapter for FTP supports the business objects with null namespaces.

The adapter supports the business objects with null namespaces. You can configure the namespace value of the business object using the Business Object Editor tool which is provided by the IBM Integration Designer.

Use the default value provided by the IBM Integration Designer, for example, http://ModuleName and configure the null namespaces. If a business object is created using the tool, the default namespace will be set as the module name. This can be modified with any other value or set to null.


Feedback


Business object attribute properties

Business object architecture defines various properties that apply to attributes. This section describes how the adapter interprets these properties.

The following table describes these properties and how the adapter interprets them.

Business object attribute properties

Property Description
Cardinality For simple attributes, 1 is used. For container attributes, depending on the method requirements, n is used.
Foreign Key The adapter does not have any specific elements representing Foreign Keys.
Key The adapter does not have any specific elements representing a Key.
Name This property represents the unique name of the attribute, if it is a simple attribute, or the name of the business object, if it is a child business object.
Required This property specifies whether an attribute must contain a value.
Type The attribute type can be either simple or complex. Simple types are: Boolean, String, LongText, Integer, Float, Double and Byte[]. A typical complex type is the name of another business object.


Feedback


Business object operation support

An operation is the name of the action that is performed on the business object by the adapter. Every business object has an operation associated with it. The name of the operation typically indicates the type of action that is taken on the business object.

The following table defines the operations the adapter supports.

Supported operations of business objects

Operation Result
Create Creates a file with the specified file name in the specified directory with the content sent across in the request.
Append Appends the content in the request to the end of the file.
Retrieve Returns the content of the file specified in the request.
Delete Deletes the file from the directory specified in the request.
Overwrite Overwrites the file in the directory with the content specified in the request.
Exists Returns a successful response if the file in the request exists in the specified directory or sub directories.
List Returns all the file names in the specified directory.
ServerToServerFileTransfer Transfers the file from one FTP server to another FTP server.
ExecuteFTPScript Runs an FTP script file in the specified directory.


Feedback


Custom business objects

If you use custom business objects, create predefined business objects using the IBM Integration Designer business object wizard before running the external service wizard. The business object definitions created by the wizard are stored as .xsd files on your local system. When the external service wizard creates the business objects, it looks for the predefined business objects created in the business object wizard and populates them with the data specific to the module.

For more information about how to create the predefined business objects, see IBM Integration Designer documentation.


Feedback


Custom file splitting

You can implement a custom class containing the splitting logic. The adapter provides a Javaâ„¢ interface for the class. WebSphere Adapter for FTP, version 7.5 supports additional splitting methods for the inbound process. Hence, there are two different interfaces available for the inbound and outbound process.


Interface for outbound operations

Use the com.ibm.j2ca.utils.filesplit.SplittingFunctionalityInterface interface for the outbound operations.

Following are the details of the interface: 

public interface SplittingFunctionalityInterface extends Iterator{
  public int getTotalBOs(String filename) throws SplittingException;
public void setBODetails(String filename, int currentPosition, int totalBOs,
  boolean includeEndBODelimiter) throws SplittingException;
   public void setSplitCriteria(String splitCriteria);
   public void setEncoding(String encoding);
   public void setLogUtils(LogUtils logUtils);
public boolean isSplitBySize()}


Interface for inbound operations

Use the com.ibm.j2ca.utils.filesplit.InboundSplittingFunctionalityInterface interface for the inbound operations.

The custom splitting class for an inbound operation created in the earlier version of the adapter does not work with version 7.5.

Following are the details of the interface: 

public interface InboundSplittingFunctionalityInterface{
 public Hashtable getBOs(String filename,int quantity, long lastBO,long lastBOPos,boolean withDelim) throws SplittingException,MissingDataException;
 public void setBODetails(String filename, long currentBO, long startPos, long endPos) throws SplittingException;
 public Object getBOContent();
 public boolean hasMoreBO();
 public void remove();
 public void setSplitCriteria(String splitCriteria);
 public void setEncoding(String encoding);
 public void setLogUtils(LogUtils logUtils);
 public boolean isSplitBySize();}



Related concepts:

Inbound processing

Feedback


Fault business objects

The adapter supports business faults, which are exceptions that are anticipated and declared in the outbound service description, or import. Business faults occur at predictable points in a business process, and are caused by a business rule violation or a constraint violation.

The adapter provides the following fault business objects the wizard creates:


Feedback


Outbound configuration properties

IBM WebSphere Adapter for FTP has several categories of outbound connection configuration properties, which you set with the external service wizard while generating or creating objects and services. You can change the resource adapter and managed connection factory properties after you deploy the module to IBM Business Process Manager or WebSphere Enterprise Service Bus using IBM Integration Designer or the administrative console, but connection properties for the external service wizard cannot be changed after deployment.



Related reference:

Inbound configuration properties

Feedback


Resource adapter properties

The resource adapter properties control the general operation of the adapter, such as specifying the namespace for business objects. You set the resource adapter properties using the external service wizard when you configure the adapter. After deploying the adapter, use the administrative console to change these properties.

The following properties for logging and tracing are no longer required in version 7.5.0.2, but are supported for compatibility with previous versions:

The following table lists the resource adapter properties and their purpose. 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.

Resource adapter properties for the WebSphere Adapter for FTP

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.

EISEncoding EISEncoding Encode of the FTP server.
(Not available)

enableHASupport

Do not change this property.

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.
(Not available)

LogFileSize

Deprecated
(Not available)

LogFilename

Deprecated
(Not available)

LogNumberOfFiles

Deprecated
(Not available)

TraceFileSize

Deprecated
(Not available)

TraceFileName

Deprecated
(Not available)

TraceNumberOfFiles

Deprecated


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 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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


EISEncoding (EISEncoding)

This property specifies the encoding of the FTP server. Sets the encoding for the control connection while communicating with the FTP server. Set the property if the FTP server's directories or file names contain globalized characters.

EISEncoding characteristics

Required No
Default None
Property type String
Examples UTF-8, ISO-8859-1


Enable high availability support (enableHASupport)

Do not change this property. It must be set to true.


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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Log file maximum size (LogFileMaxSize)

This property specifies the size of the log files in kilobytes.

Log file maximum size details

Required No
Default 0
Property type Integer
Usage When the log file reaches it maximum size, the adapter start using a new log file. If the file size is specified as 0 or no maximum size is specified, the file does not have a maximum size.
Globalized Yes
Bidi supported No


Log file name (LogFilename)

This property specifies the full path name of the log file.

Log file name details

Required No
Default No default value
Property type String
Usage This property is deprecated.
Globalized Yes
Bidi supported Yes


Log number of files (LogNumberOfFiles)

This property specifies the number of log files.

Log number of files details

Required No
Default 1
Property type Integer
Usage When a log file reaches its maximum size, the adapter starts using another log file. If no value is specified, the adapter creates a single log file.
Globalized Yes
Bidi supported No


Trace file maximum size (TraceFileMaxSize)

This property specifies the size of the trace files in kilobytes.

Trace file maximum size details

Required No
Default 0
Property type Integer
Usage If no value is specified, then the trace file has no maximum size.
Globalized Yes
Bidi supported No


Trace file name (TraceFilename)

This property specifies the full path of the trace file.

Trace file name details

Required No
Default No default value
Unit of measure Kilobytes
Property type String
Usage This property is deprecated.
Globalized Yes
Bidi supported Yes


Trace number of files (TraceNumberOfFiles)

This property specifies the number of trace files to use. When a trace file reaches its maximum size, the adapter starts using another trace file.

Trace number of files details

Required No
Default 1
Property type Integer
Usage If no value is specified, the adapter uses a single trace file.
Globalized Yes
Bidi supported No



Related tasks:

Generating the service

Feedback


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 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 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
Encode 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 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 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 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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure 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 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 the data transfer will be integrity and confidentiality protected.
  • Clear – Indicates 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 used during outbound operations.

Default target file name property characteristics

Required Yes
Default Yes
Property type String

Usage

Use the WAS environment variable to represent the file name directory. Set the name of the environment variable within braces, preceded by a $ symbol. For example: ${FILENAME}. See Defining WAS environment variables.

Globalized No


Directory property (outputDirectory)

The property specifies the output directory in the FTP Server 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 WAS environment variable to represent the output directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${OUTPUT_DIRECTORY}. See Defining WAS 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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


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

Disable 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 specifies 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 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 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

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 WAS environment variable to represent the staging directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${STAGING_DIRECTORY}. See the topic on Defining WAS 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



Related tasks:

Generating the service

Feedback


Wrapper and interaction specification properties

Wrapper properties are attributes of the wrapper business object that enable an application programmer to control an operation for the business objects in a wrapper. Interaction specification properties control the interaction for an operation for the entire adapter.

The external service wizard sets the interaction specification properties when you configure the adapter. You can change some, but not all, of these properties. However, you can change some properties for outbound operations. Use the assembly editor to change these properties, which reside in the method binding of the import. You set the wrapper properties using the Integration Designer test client or programmatically at run time.

The values set in the business object wrapper properties take precedence over the interaction specification properties, even if a NULL value is set. If the values are not set in the business object wrapper properties, then the adapter uses the values set in the interaction specification properties. The adapter uses the values set in the Managed (J2C) connection factory properties if the values are not set in the wrapper and the interaction specification properties.

The following table lists the wrapper and interaction specification 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.

Interaction specification properties

Property name Description
In the wizard In the wrapper business object
Remote archive directory for retrieve operation ArchiveDirectoryForRetrieve The adapter optionally archives the file to this folder before it is deleted during a Retrieve operation.
Create new file if the file does not exist CreateFileIfNotExists If the file does not exist on the FTP server, the adapter creates the file when this property is set to True during Append and Overwrite operations.
FTP server connection mode DataConnectionMode Data connection mode used by the FTP server during file transfers.
Delete the file after retrieve operation DeleteOnRetrieve The adapter deletes the file from the FTP server after it is retrieved when this property is set to True.
Remote directory on FTP system DirectoryPath Absolute path of the directory on the FTP server where the outbound operation must be performed.
Data channel protection level dataProtectionLevel Specifies the protection level of a data channel in case of FTPS protocol.
File content encoding FileContentEncoding Encode used while writing to the file.
File in local directory FileInLocalDirectory If set to True during a create operation, the file content is picked from the local directory path of the adapter workstation.
Default target file name Filename Name of the file in the directory provided by the DirectoryPath property.
File transfer type FileTransferType File transfer type used during outbound operations.
Generate a unique file GenerateUniqueFile The adapter creates a unique file name when this property is set to True.
Host name property SecondServerHostName Host name of the second FTP server.
Delimiter between business objects in the file property IncludeEndBODelimiter File content is appended with this value.
Local archive directory for create operation LocalArchiveDirForCreate When LocalArchivingEnabledForCreate is set to True during a create operation, the file is saved to the local workstation in this directory.
Archive file in the local directory for create operation LocalArchivingEnabledForCreate When set to True, the file is saved to the local workstation during a create operation.
Local directory LocalDirectoryPath The file is picked from this directory.
Prefix for the unique file name UniqueFilePrefix Specifies the prefix for generating the unique file names during the outbound Create operation.
(Not available) ResumeFailedTransfer When this property is set to True during a create operation, the adapter resumes the transfer of files from the point at which the transfer of file was interrupted due to connection error.
Port number SecondServerPortNumber Port number of the second FTP server.
Protocol SecondServerProtocol Specifies the protocol used to connect to the second server.
Script File Parameters ScriptFileParameters The parameters required by the FTP script file.
Directory SecondServerDirectory Directory path of the second FTP server during a ServerToServerFileTransfer operation.
Password SecondServerPassword Password of the second FTP server during a ServerToServerFileTransfer operation.
User name SecondServerUsername User name of the second FTP server during a ServerToServerFileTransfer operation.
Specify criteria to split file content SplitCriteria The delimiter that separates the business objects in the event file.
Split function class name SplittingFunctionClassName The fully qualified class name of the class file to be used to enable file splitting.
Staging directory StagingDirectory The file is first created into this directory.
Suffix for the unique file name UniqueFileSuffix Specifies the suffix for generating the unique file names during the outbound Create operation.
Temporary file name TemporaryFilename Specifies the temporary file name for the create operation.


Archive file in the local directory for create operation property (LocalArchivingEnabledForCreate)

During outbound create operations, when the file content is coming as part of the business object from a Java EE application and this property is set to True, the file is saved to the local workstation in the LocalArchiveDirForCreate directory before performing the outbound operation.

Archive file in the local directory for create operation property characteristics

Required No
Default False
Property type Boolean
Globalized No


Create new file if the file does not exist property (CreateFileIfNotExists)

During outbound Append and Overwrite operations, if the file does not exist on the FTP server, the adapter creates the file when this property is set to True. If this property is False and file does not exist, the adapter sends an error.

Create new file if the file does not exist property characteristics

Required No
Default False
Property type Boolean
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 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 the data transfer will be integrity and confidentiality protected.
  • Clear – Indicates 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


Delete the file after retrieve operation (DeleteOnRetrieve)

During an outbound Retrieve operation, the adapter deletes the file from the FTP server after it is retrieved when this property is set to True.

Delete the file after retrieve operation property characteristics

Required No
Default False
Property type Boolean
Globalized No


Default target file name property (Filename)

Name of the file to be used during outbound operations.

Default target file name property characteristics

Required No
Default None
Property type String
Globalized Yes


Delimiter between business objects in the file property (IncludeEndBODelimiter)

File content is appended with this value. Used during the outbound create, append, and overwrite operations.

Include business object delimiter in the file content property characteristics

Required No
Default

For the create and overwrite operations, no default value is set.

For the append operation, the default value is <EndBO>.

For the append operation, the following rules apply:

  • If the delimiter is set to null in the business object wrapper, no delimiter is used to separate the business objects.

  • If the IncludeEndBODelimiter property is not set in the business object wrapper, and the value in the interaction specification is also null, the default is <EndBO>.

  • If a specific delimiter value is specified in the business object wrapper, the specified value will be appended.

  • If both the business object wrapper and the interaction specification have specified values, the business object wrapper value takes precedence.

Property type String
Globalized Yes


Directory property (SecondServerDirectory)

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

Directory property characteristics

Required No
Default None
Property type String
Usage For interaction specification properties, the directory located on the FTP server and used in outbound operation represents the absolute path of the FTP directory. For example: /home/usr/output. It does not contain any host name or URL information.

For wrapper business object properties, the URL of the second server to which the ServerToServerFileTransfer outbound operation is performed. For example: The syntax for specifying the FTP URL is: ftp://[UserId:password@]FTPserver[:port]/DirectoryForSecondServer.

Globalized Yes


File content encoding property (FileContentEncoding)

Encoding used while writing to the file. If this property is not specified, the adapter tries to read without using any specific encoding. You can specify any Javaâ„¢ supported encoding set.

File content encoding property characteristics

Required No
Default None
Property type String
Globalized No


File in local directory property (FileInLocalDirectory)

During outbound create operations, if this property is set to True, the file content is not available in the business object. The file is retrieved from the local directory on the adapter workstation. During outbound retrieve operations, if this property is set to True, the file content is not sent to the Java EE application as part of the business object. The file is saved to the local directory of the adapter workstation.

File in local directory property characteristics

Required No
Default False
Property type Boolean
Globalized No


File transfer type property (FileTransferType)

File transfer type used during outbound operations. Takes either ASCII or binary.

File transfer type property characteristics

Required No
Default binary
Property type String
Globalized No


FTP server connection mode property (DataConnectionMode)

This property represents the data connection mode used by the FTP server during file transfers. This value is used only when a file transfer is taking place. This property is not used when performing a server to server file transfer outbound operation.

FTP server connection mode property characteristics

Required No
Possible values active or passive
Default active
Property type String
Usage If the adapter is behind the firewall, set this property value as passive. If the FTP server is behind the firewall, set this property value as active.
Globalized No


Generate a unique file property (GenerateUniqueFile)

This property specifies if the adapter generates unique file name for the files created during the outbound Create operation.

The adapter does not support both GenerateUniqueFile and StagingDirectory options at the same time.

Generate unique file property characteristics

Required No
Possible values

True False

Default False
Property type Boolean
Usage When this property is set to True,

  • the adapter generates a unique name for the files
  • the adapter ignores any value that is set for the Filename property
  • optionally, allows you to specify the prefix and/or suffix for generating unique file names

Globalized No


Prefix for the unique file name property (UniqueFilePrefix)

This property specifies the prefix for generating the unique file names during the outbound Create operation.

Prefix for the unique file name property characteristics

Required No
Default None
Property type String
Usage During the Create operation, the adapter generates unique file names prefixed with the value specified in this property.
Globalized Yes


Suffix for the unique file name property (UniqueFileSuffix)

This property specifies the suffix for generating the unique file names during the outbound Create operation.

Suffix for the unique file name property characteristics

Required No
Default None
Property type String
Usage During the Create operation, the adapter generates unique file names suffixed with the value specified in this property.

To add a file name extension, specify the period (.) in this property. For example, if the prefix is "abc" and suffix is ".xyz", then the format of the file name is "abc12345678.xyz".

Globalized Yes


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
Globalized Yes


Local archive directory for create operation property (LocalArchiveDirForCreate)

During outbound create operations, when the file content is coming as part of the business object and LocalArchivingEnabledForCreate is set to True, the file is saved to the local workstation in this directory.

Local archive directory for create property characteristics

Required No
Default None
Property type String
Usage The LocalArchiveDirForCreate directory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.
Globalized Yes


Local directory property (LocalDirectoryPath)

During outbound create operations, when FileInLocalDirectory property is set to True, the file content is not available in the business object. Instead the file is picked from this directory. During outbound retrieve operations, when FileInLocalDirectory property is set to True, the file content is not sent as part of business object. The file is saved to this directory.

Local directory property characteristics

Required No
Default None
Property type String
Usage The LocalDirectoryPath directory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.
Globalized Yes


Port number property (SecondServerPortNumber)

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


Protocol property (SecondServerProtocol)

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


Password property (SecondServerPassword)

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


Remote archive directory for retrieve operation property (ArchiveDirectoryForRetrieve)

During an outbound Retrieve operation, the adapter archives the file to this folder before the files are deleted.

Remote archive directory for retrieve operation property characteristics

Required No
Default None
Property type String
Usage The archive directory must exist. The adapter must have read and write permissions on the archive directory to archive the file during the outbound Retrieve operation.
Globalized Yes


Remote directory on FTP system property (DirectoryPath)

Absolute path of the directory on the FTP server where the outbound operation must be performed for all operations except ExecuteFTPScript, or the directory path on the local adapter workstation for the ExecuteFTPScript operation only. The directory must exist.

If the value <HOME_DIR> is specified as the DirectoryPath, the outbound operations will be performed in the users home directory.

Remote directory on FTP system property characteristics

Required No
Default None
Property type String
Usage

The DirectoryPath directory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.

Globalized Yes


ResumeFailedTransfer

This property supports resuming the transfer of files, which were interrupted due to an error in connection to the FTP server.

This property is applicable only to outbound processing.

ResumeFailedTransfer property characteristics

Required No
Default False
Property type Boolean
Usage

During a create operation, when this property is set to True, the adapter resumes the transfer of files from the point at which the transfer of file was interrupted due to an error in connection.

Globalized No


Script File Parameters property (ScriptFileParameters)

During an outbound ExecuteFTPScript operation, the parameters required by the FTP script file are set in this property. During run time, the adapter replaces the parameters with these values.

Script File Parameters property characteristics

Required No
Default None
Property type String
Globalized Yes


Specify criteria to split file content property (SplitCriteria)

This property accepts different values based on the value of the SplittingFunctionClassName property.

Specify criteria to split file content property characteristics

Required No
Default 0
Property type String
Globalized Yes


Split function class name property (SplittingFunctionClassName)

Takes the fully qualified class name of the class file to be used to enable file splitting. Requires two values:

The delimiter or file size is provided in the SplitCriteria property.

Split function class name property characteristics

Required No
Default com.ibm.j2ca.utils.filesplit.SplitBySize
Property type String
Globalized No


Staging directory property (StagingDirectory)

During outbound create operations, the file will be created in this directory first. When the file creation is complete, the file is copied to the directory specified in the DirectoryPath property. This staging directory is also used for Append and Overwrite operations where the specified file is copied to the StagingDirectory, if present. The appended or overwritten content is then moved back to the original specified directory. If StagingDirectory is not specified, the operation is run in the actual required directory.

The adapter does not support both StagingDirectory and GenerateUniqueFile options at the same time.

Staging directory property characteristics

Required No
Default None
Property type String
Usage The StagingDirectory directory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.
Globalized Yes


Temporary file name property (TemporaryFilename)

This property specifies the temporary file name for the create operation. After successful creation of the file, the file gets renamed to the value specified in the 'Default target file name' property.

Temporary file name property characteristics

Required No
Possible values All valid file names
Default None
Property type String
Usage This property is used in the create operation. If the temporary file name is specified, the file is created with the temporary file name. After the file is successfully created, the file is renamed to the value specified in the 'Default target file name' property.
Example xyz.tmp
Globalized No


User name property (SecondServerUsername)

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



Related concepts:

Supported operations


Related tasks:

Change interaction specification properties

Feedback


Inbound configuration properties

WebSphere Adapter for FTP has several categories of inbound connection configuration properties, which you set with the external service wizard while generating or creating objects and services. You can change the resource adapter and activation specification properties after you deploy the module using IBM Integration Designer or the administrative console, but connection properties for the external service wizard cannot be changed after deployment.



Related reference:

Outbound configuration properties

Feedback


Resource adapter properties

The resource adapter properties control the general operation of the adapter, such as specifying the namespace for business objects. You set the resource adapter properties using the external service wizard when you configure the adapter. After deploying the adapter, use the administrative console to change these properties.

The following properties for logging and tracing are no longer required in version 7.5.0.2, but are supported for compatibility with previous versions:

The following table lists the resource adapter properties and their purpose. 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.

Resource adapter properties for the WebSphere Adapter for FTP

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.

EISEncoding (EISEncoding) EISEncoding Encode of the FTP server.
Disguise user data as "XXX" in log and trace files (HideConfidentialTrace) HideConfidentialTrace Specifies whether to disguise potentially sensitive information by writing X strings instead of user data in the log and trace files.
(Not available) enableHASupport Specifies the configuration mode, Active-Active or Active-Passive, for the WebSphere Adapter for FTP.
(Not available)

LogFileSize

Deprecated
(Not available)

LogFilename

Deprecated
(Not available)

LogNumberOfFiles

Deprecated
(Not available)

TraceFileSize

Deprecated
(Not available)

TraceFileName

Deprecated
(Not available)

TraceNumberOfFiles

Deprecated


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 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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized Yes
Bidi supported No


EISEncoding (EISEncoding)

This property specifies the encoding of the FTP server. Sets the encoding for the control connection while communicating with the FTP server. Set the property if the FTP server's directories or file names contain globalized characters.

EISEncoding characteristics

Required No
Default None
Property type String
Examples UTF-8, ISO-8859-1


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 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 using the IBM Integration Designer assembly editor or the administrative console to reset these properties, ensure set them consistently, to prevent inconsistent marking of the log and trace entries.

Globalized No
Bidi supported No


Log file maximum size (LogFileMaxSize)

This property specifies the size of the log files in kilobytes.

Log file maximum size details

Required No
Default 0
Property type Integer
Usage When the log file reaches it maximum size, the adapter start using a new log file. If the file size is specified as 0 or no maximum size is specified, the file does not have a maximum size.
Globalized Yes
Bidi supported No


Log file name (LogFilename)

This property specifies the full path name of the log file.

Log file name details

Required No
Default No default value
Property type String
Usage This property is deprecated.
Globalized Yes
Bidi supported Yes


Log number of files (LogNumberOfFiles)

This property specifies the number of log files.

Log number of files details

Required No
Default 1
Property type Integer
Usage When a log file reaches its maximum size, the adapter starts using another log file. If no value is specified, the adapter creates a single log file.
Globalized Yes
Bidi supported No


Trace file maximum size (TraceFileMaxSize)

This property specifies the size of the trace files in kilobytes.

Trace file maximum size details

Required No
Default 0
Property type Integer
Usage If no value is specified, then the trace file has no maximum size.
Globalized Yes
Bidi supported No


Trace file name (TraceFilename)

This property specifies the full path of the trace file.

Trace file name details

Required No
Default No default value
Unit of measure Kilobytes
Property type String
Usage This property is deprecated.
Globalized Yes
Bidi supported Yes


Trace number of files (TraceNumberOfFiles)

This property specifies the number of trace files to use. When a trace file reaches its maximum size, the adapter starts using another trace file.

Trace number of files details

Required No
Default 1
Property type Integer
Usage If no value is specified, the adapter uses a single trace file.
Globalized Yes
Bidi supported No


Enable high availability support (enableHASupport)

This property specifies the configuration mode, either Active-Active or Active-Passive, for the WebSphere Adapter for FTP in a clustered environment.

For HA Active-Active configuration, this property must be set to False in the administrative console.

Enable high availability support property details

Required No
Possible values True

False

Default True
Property type Boolean
Usage

Active-Passive configuration mode

By default (enableHASupport=True), the adapter is set to Active-Passive configuration mode, providing high availability support. This configuration mode allows only one adapter instance to be active and to poll a remote event directory for files.

Active-Active configuration mode

When this property is set to False, the adapter is in the Active-Active configuration mode. The adapter in the Active-Active configuration mode provides both high availability and load balancing support. Different adapter instances process different events, in parallel. This results in each adapter instance polling for a unique event and delivering the event without any duplication, to the endpoint.

If an adapter is configured to support high availability Active-Active mode, then configure all event persistence properties. In addition, the following are not supported in this configuration mode:

  • Sorting of event files (by file name or timestamp) being polled
  • Ordered delivery type of events to the export

Globalized No
Bidi supported No


Feedback


Activation specification properties

Activation specification properties are properties that hold the inbound event processing configuration information for a message endpoint.

Activation specification properties are used during endpoint activation to notify the adapter of eligible event listeners. During inbound processing, the adapter uses these event listeners to receive events before forwarding them to the endpoint (a message driven bean).

You set the activation specification properties using the external service wizard and can change them using the IBM Integration Designer Assembly Editor, or after deployment through the administrative console.

The following table lists the activation specification 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.

Activation specification properties

Property name Description
In the wizard In the administrative console
Ensure once-only event delivery (assuredOnceDelivery) assuredOnceDelivery

Specifies whether the adapter provides assured once delivery of events.

Auto create tables property (EP_CreateTable) EP_CreateTable

Specifies if the adapter should create an Event Persistence table.

Custom parser class name property (customParserClassName) customParserClassName

Fully qualified class name of the custom parser which is used to parse the ls –l output.

Data channel protection level (dataProtectionLevel) dataProtectionLevel Specifies the protection level of a data channel in case of FTPS protocol.
Database schema name property (EP_SchemaName) EP_SchemaName

Schema name of the database used by event persistence.

FTP server connection mode property (dataConnectionMode) dataConnectionMode

Data connection mode used by the FTP server during file transfers.

FTPS connection mode property (ftpsConnectionMode) ftpsConnectionMode

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

(Not available) defaultObjectName

Supported for compatibility with earlier versions.

Delivery type (deliveryType) deliveryType

Determines the order in which events are delivered by the adapter to the export.

Encode used by FTP server property (EISEncoding) EISEncoding

Encoding of the FTP server.

(Not available) eventContentType

Supported for compatibility with earlier versions.

Event recovery data source (JNDI) name property (EP_DataSource_JNDIName) EP_DataSource_JNDIName

JNDI name of the data source used by event persistence to get the JDBC database connection.

Table name to store the event persistence information property (EP_TableName) EP_TableName

Name of the table used by the adapter for event persistence.

Table name to store the file processing status (EP_FileTableName) EP_FileTableName The name of the table used to store the file processing status.
Failure file extension for local archive property (failedArchiveExt) failedArchiveExt

File extension used to archive business objects in the event file that are not successfully processed.

File content encoding property (fileContentEncoding) fileContentEncoding

Encoding used to read the event files.

File extension for remote archive property (ftpRenameExt) ftpRenameExt

File extension or suffix the adapter uses to rename the remote FTP file.

Keystore file property (keyStorePath) keyStorePath Specifies the path of the keystore that contains the private key entries.
Keystore password property (keyStorePassword) keyStorePassword Specifies the password used to encrypt the keystore.
Key password property (keyPassword) keyPassword Specifies the password used to encrypt the key.
Keystore type property (keyStoreType) keyStoreType Specifies the type of the keystore.
Pass only file name and directory, not the content property (filePassByReference) filePassByReference

Specifies the file content of the event file is not sent to the export.

File transfer type property (fileTransferType) fileTransferType

File transfer type used during inbound processing.

Number of files to get at a time property (ftpGetQuantity) ftpGetQuantity

Determines the number of files retrieved from the remote FTP URL.

Number of poll periods between downloads property (ftpPollFrequency) ftpPollFrequency

Determines how frequently the adapter polls the FTP server.

Retry limit for failed events failedEventRetryLimit The number of times the adapter attempts to redeliver an event before marking the event as failed.
Run FTP script file after downloading files property (ftpScriptFileExecutedAfterInbound) ftpScriptFileExecutedAfterInbound

Specifies the path of the script file that will be executed after downloading the files from the FTP server.

Run FTP script file before downloading files property (ftpScriptFileExecutedBeforeInbound) ftpScriptFileExecutedBeforeInbound

Specifies the path of the script file that is executed before downloading the files from the FTP server.

Host name property (hostName) hostName

Host name of the FTP Server to which the connection is established.

Include business object delimiter in the file content property (includeEndBODelimiter) includeEndBODelimiter

When set to True, the delimiter is sent with the business object content for further processing.

Include total business object count in the ChunkInfo (includeBOCountInChunkInfo)

includeBOCountInChunkInfo

When set to true, the total business object count is included in the chunk information of the dataobject sent to the endpoint.

Local archive directory property (localArchiveDirectory) localArchiveDirectory

Absolute path of the local Archive directory.

Local directory property (localEventDirectory) localEventDirectory

Local system directory into which the adapter downloads event files from the FTP site.

File extension for local archive property (originalArchiveExt) originalArchiveExt

File extension used to archive the original event file.

Passphrase property passPhrase Used for enhanced security by encrypting the private key
Password property (password) password

Password of the user who has privileges to connect to the FTP server and perform FTP operations.

Password used to connect to event data source property (EP_Password) EP_Password

Password used during event persistence.

Interval between polling periods (pollPeriod) pollPeriod

The length of time the adapter waits between polling periods.

Maximum events in polling period (pollQuantity) pollQuantity

The number of events the adapter delivers to the export during each poll period.

Port number property (portNumber) portNumber

Port number of the FTP server.

Private key file property (privateKeyFilePath) privateKeyFilePath

Private key used to authenticate to the Secure shell server.

Protocol property (protocol) protocol

Specifies if the connection to the FTP server is normal FTP or secure FTP.

Retrieve files with this pattern property (eventFileMask) eventFileMask

Filter for the event files.

Retry EIS connection on startup retryConnectionOnStartup

Controls whether the adapter retries the connection to the FTP server if it cannot connect at startup.

Time between retries in case of system connection failure (milliseconds) retryInterval

The length of time the adapter waits between attempts to reestablish connection after an error during inbound operations.

Maximum number of retries in case of system connection failure retryLimit

The number of times the adapter tries to reestablish an inbound connection after an error.

Remote archive directory property (ftpArchiveDirectory) ftpArchiveDirectory

Relative path of the archive directory on the FTP server.

Remote directory property (eventDirectory) eventDirectory

Remote directory of the FTP server from where the event files are retrieved for inbound processing.

Verify remote directory access permission (isPermissionCheckEnabled) isPermissionCheckEnabled

Specifies if the access permissions for the event directory must be verified before performing the inbound operation.

Enable server verification enableServerVerification Enables the remote server verification for SFTP protocol.
Host key file hostKeyFile The absolute path of the host key file that contains the host keys of the trusted servers.
Host name property (socksProxyHost) socksProxyHost

Host name of the machine used as a proxy server.

Password property (socksProxyPassword) socksProxyPassword

Password used to authenticate the proxy server.

Port number property (socksProxyPort) socksProxyPort

Port number of the proxy server.

User name property (socksProxyUserName) socksProxyUserName

User name used to authenticate the proxy server.

Sort event files property (sortEventFiles) sortEventFiles

Determines the sorting order of event files being polled.

Specify criteria to split file content property (splitCriteria) splitCriteria

Accepts different values based on the value of the SplittingFunctionClassName property.

Splitting function class name property splittingFunctionClassName

Accepts the fully qualified class name of the class file to be used to enable file splitting.

Stop the adapter when an error is encountered while polling (stopPollingOnError) stopPollingOnError

Specifies whether the adapter stops polling for events when it encounters an error during polling.

Success file extension for local archive property (successArchiveExt) successArchiveExt

File extension used to archive all the successfully processed business objects.

Truststore file property (trustStorePath) trustStorePath Specifies the path of the truststore file that contains the certificates of the FTPS servers trusted by the adapter.
Truststore password property (trustStorePassword) trustStorePassword Specifies the password of the truststore.
Time interval for polling unchanged files (fileUnchangedTimeInterval) fileUnchangedTimeInterval

Specifies the time interval for the adapter to monitor the files for any updates in the content.

User name property (userName) userName

Name of the user who has privileges to connect to the FTP server and perform FTP operations.

User name used to connect to event data source property (EP_UserName) EP_UserName

User name used by event persistence for getting the database connection.

Rule editor to filter files ruleTable The collection of rules used to filter the events.
Enable remote verification property (enableRemoteVerification) 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.

Time out period for HA Active-Active event processing change (in seconds) (EP_Timeout)

EP_Timeout

Specifies the time interval for processing the events fetched.


Ensure once-only event delivery (assuredOnceDelivery)

This property specifies whether to provide ensure once-only event delivery for inbound events.

Ensure once-only event delivery details

Required Yes
Possible values

True False

Default True
Property type Boolean
Usage When this property is set to True, the adapter provides assured once event delivery. This means that each event is delivered once and only once. A value of False does not provide assured once event delivery, but provides better performance.

When this property is set to True, the adapter attempts to store transaction (XID) information in the event store. If it is set to False, the adapter does not attempt to store the information.

This property is used only if the export component is transactional. If it is not, no transaction can be used, regardless of the value of this property.

Globalized No
Bidi supported No


Auto create tables property (EP_CreateTable)

This property specifies if the adapter creates the event persistence table and the file table.

Auto create tables property characteristics

Required No
Possible values

True False

Default True
Property type Boolean
Usage If the value is set to True, and the tables do not exist, then the adapter creates the tables, automatically. If the value is set to False, the adapter does not create the tables.

The tables are created automatically only for the following databases.

  • IBM DB2
  • Oracle
  • Microsoft SQL Server
  • Apache Derby

For other databases, you must manually create the event table and the file table.

Globalized No


Custom parser class name property (customParserClassName)

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

Custom parser class name property characteristics

Required No
Default No default value
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 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 the data transfer will be integrity and confidentiality protected.
  • Clear – Indicates 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


Database schema name property (EP_SchemaName)

Schema name of the database used by event persistence.

Database schema name property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Delivery type (deliveryType)

This property specifies the order in which events are delivered by the adapter to the export.

Delivery type details

Required No
Possible values

ORDERED UNORDERED

Default ORDERED
Property type String
Usage The following values are supported:

  • ORDERED: The adapter delivers events to the export one at a time.
  • UNORDERED: The adapter delivers all events to the export at once.

HA Active-Active configuration supports only unordered delivery type events to the export.

Globalized No
Bidi supported No


Encode 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 No default value
Property type String
Globalized Yes


Event recovery data source (JNDI) name property (EP_DataSource_JNDIName)

JNDI name of the data source used by event persistence to get the JDBC database connection. The data source must be created in BPM. The database name specified while creating the data source must exist.

Event recovery data source (JNDI) name property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Table name to store the event persistence information property (EP_TableName)

Name of the table used by the adapter for event persistence. When using multiple activation specifications, this value must be unique for each. The same table name must not be used by other instances of same adapter or a different adapter. If the table does not exist in the database, the adapter creates the table, when the EP_CreateTable property is set to True.

Table name to store the event persistence information property characteristics

Required No
Default FTPTABLE
Property type String
Globalized Yes


Table name to store the file processing status (EP_FileTableName)

This property specifies the table name to store the file processing status. The adapter continues to process the file from its last stored status, during the event recovery.

Table name to store the file processing status (EP_FileTableName) details

Required No
Default FTP_FILETABLE
Property type String
Usage

This property supports WebSphere Adapter for FTP to read only the partial contents of the file required by the polling quantity and tracks the last file position reached after a partial read of the file. The file status stored in the table is used during the event recovery.

During the event recovery, the adapter continues to process the file from its last stored status in the table.

Globalized Yes
Bidi supported Yes


FTP server connection mode property (dataConnectionMode)

This property represents the data connection mode used by the FTP server during file transfers.

FTP server connection mode property characteristics

Required No
Possible values active or passive
Default active
Property type String
Usage If the adapter is behind the firewall, set this property value as passive. If the FTP server is behind the firewall, set this property value as active.
Globalized No


FTPS connection mode property (ftpsConnectionMode)

This property specifies the connection mode when establishing a connection with the FTPS server. 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


Failure file extension for local archive property (failedArchiveExt)

File extension used to archive business objects in the event file that are not successfully processed. This property is used only when localArchiveDirectory is valid and exists.

Failure file extension for local archive property characteristics

Required No
Default fail
Property type String
Globalized Yes


File content encoding property (fileContentEncoding)

Encoding used to read the event files based on the EndBODelimiter property and during string to byte[] conversions. If not specified, the adapter attempts to read without any specific encoding. You can specify any Javaâ„¢ supported encoding set.

File content encoding property characteristics

Required No
Default No default value
Property type String
Globalized No


File extension for remote archive property (ftpRenameExt)

File extension or suffix the adapter uses to rename the remote FTP file after the connector has polled for it. Renaming the file prevents the connector from polling the same file in the next poll cycle. The adapter can be configured to rename the processed event file and move it to an archive directory.

File extension for remote archive property characteristics

Required No
Default No default value
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


Time interval for polling unchanged files (fileUnchangedTimeInterval)

This property specifies the time interval for the adapter to monitor the files for any updates in the content. The adapter polls only those files that are not changed during the specified time interval.

Time interval for polling unchanged file

Required No
Default 0
Unit of measure Milliseconds
Property type Integer
Usage This property enables the adapter to poll only those files that are not modified in the event directory for a specified time interval. When this property is selected, the adapter retrieves the unchanged files during the poll cycles. The adapter also polls the files that are currently being edited but retrieves the file content present during the last save of the file.

If the value is set to '0' the adapter polls the files instantly and does not check if the files are being modified.

The minimum value for this property is 0. If you set a value less than 0, an error message is displayed.

Globalized No
Bidi supported No


Pass only file name and directory, not the content property (filePassByReference)

Specifies the file content of the event file is not sent to the export.

Pass only file name and directory, not the content property characteristics

Required No
Default False
Property type Boolean
Usage If set to True, the file is appended with a timestamp and sent to the localArchiveDirectory. The timestamp prevents errors and overwrites to the file when another file with the same name is received. This property can be set to True only when the local archive directory name is specified in the localArchiveDirectory property.

The specified directory must exist and you must have the right access permissions. This property is used only for PassThrough inbound processing. When enabled, the file is not split into chunks.

This property is disabled in the external service wizard if the Split file content based on the size (bytes) or delimiter property is selected. However, if both the filePassByReference and splittingFunctionClassName properties are set in the administrative console, the filePassByReference property takes precedence. Hence, the file is not split into chunks and the file content is not sent to the end point.

The format of the file saved in the localArchiveDirectory when this property is set to True is <FileName>_yyyy_MM_dd_HH_mm_ss_SSS, where yyyy_MM_dd_HH_mm_ss_SSS refers to the timestamp when the file was archived.

Globalized No


File transfer type property (fileTransferType)

File transfer type used during inbound processing. Accepts either ASCII or binary.

File transfer type property characteristics

Required No
Default binary
Property type String
Globalized no


Number of files to get at a time property (ftpGetQuantity)

Determines the number of files retrieved from the remote FTP URL with each remote poll.

Number of files to get at a time property characteristic

Required Yes
Default 10
Property type Integer
Usage The minimum value for this property is 1. If you set a value less than 1, an error message appears.
Globalized No


Number of poll periods between downloads property (ftpPollFrequency)

Determines how frequently the adapter polls the FTP server, measured in the number of standard poll cycles.

Number of poll periods between downloads property characteristics

Required Yes
Default 5
Property type Integer
Usage The minimum value for this property is 0. If you set a value less than 0, an error message is displayed.
Example For example, if PollPeriod is set to 10000, and ftpPollFrequency is set to 6, the adapter polls the localEventDirectory every 10 seconds and polls the remote eventDirectory every 60 seconds. The adapter performs FTP polling only if you specify a value for this property. If pollPeriod is 0, you consider it as 1 for calculation. If the calculation evaluates to 0, the adapter does not perform FTP polling.
Globalized No


Retry limit for failed events (failedEventRetryLimit)

This property specifies the number of times the adapter attempts to redeliver an event before marking the event as failed.

Retry limit for failed events details

Required No
Possible values Integers
Default 5
Property type Integer
Usage Use this property to control how many times the adapter tries to send an event before marking it as failed. It accepts the following values:

Default

If this property is not set, the adapter tries five additional times before marking the event as failed.

0

The adapter tries to deliver the event an infinite number of times. When the property is set to 0, the event remains in the event store, and the event is never marked as failed.

> 0

For integers greater than zero, the adapter retries the specified number of times before marking the event as failed.

< 0

For negative integers, the adapter does not retry failed events.
Globalized No
Bidi supported No


Run FTP script file after downloading files property (ftpScriptFileExecutedAfterInbound)

Specifies the path of the script file that will be executed after downloading the files from the FTP server.

Run FTP script file after downloading files property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Run FTP script file before downloading files property (ftpScriptFileExecutedBeforeInbound)

Specifies the path of the script file that is executed before downloading the files from the FTP server.

Run FTP script file before downloading files property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Host name property (hostName)

Host name of the FTP Server to which the connection is established during inbound processing.

Create Table property characteristics

Required Yes
Default No default value
Property type String
Globalized Yes


Include business object delimiter in the file content property (includeEndBODelimiter)

When set to True, the delimiter is sent with the business object content for further processing. This property is valid only when splitting the event files based on a delimiter.

Include business object delimiter in the file content property characteristics

Required No
Default False
Property type String
Globalized No


Include total business object count in the ChunkInfo (includeBOCountInChunkInfo)

This property, when set to true, specifies the total business object count is included in the chunk information of the dataobject, which is sent to endpoint.

Include total business object count in the ChunkInfo property characteristics

Required No
Possible values

True False

Default False
Property type Boolean
Usage

This property is used for specifying whether the total business object count is included in the chunk information of the dataobject sent to the endpoint.

Format of the chunk information:

When the property is enabled

chunksize=<LengthOfBO>;EventID=
AbsolutePathOfEventFileNameInLocalEventDirectory_/_
YYYY_MM_DD_HH_mm_ss_SSS.currentBONumber_/_TotalBOCount

When the property is disabled

chunksize=<LengthOfBO>;EventID=
AbsolutePathOfEventFileNameInLocalEventDirectory_/_
YYYY_MM_DD_HH_mm_ss_SSS.currentBONumber
Globalized No
Bidi supported No


Local archive directory property (localArchiveDirectory)

Absolute path of the local Archive directory. The directory must be valid and exist.

Local archive directory property characteristics

Required This property has to be specified if the filePassByReference property is set to True.
Default No default value
Property type String

Usage

You can use a WAS environment variable to represent the local archive directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${LOCALARCHIVE_DIRECTORY}. See Defining WAS environment variables.

  • The localArchiveDirectory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.
  • To send only the file name and the directory path to end point using the filePassByReference property, you must specify the local archive directory.

Globalized Yes


Local directory property (localEventDirectory)

Local system directory into which the adapter downloads event files from the FTP site. Specify a value for this property to enable the adapter to process events.

Local directory property characteristics

Required Yes
Default No default value
Property type String

Usage

You can use a WAS environment variable to represent the local event directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${LOCAL_DIRECTORY}. See Defining WAS environment variables.

The localEventDirectory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.

Globalized Yes


File extension for local archive property (originalArchiveExt)

File extension used to archive the original event file. This preserves the entire event file for reference in case any of its business objects fail. This property is used only when localArchiveDirectory is valid and exists.

File extension for local archive property characteristics

Required No
Default original
Property type String
Globalized Yes


Password property (password)

Password of the user who has privileges to connect to the FTP server and perform FTP operations. You do not need to specify a value for this property if the password is included in the URL specified in the eventDirectory property.

Password property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Password used to connect to event data source property (EP_Password)

The password used during event persistence to get the database connection from the data source.

Password used to connect to event data source property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Interval between polling periods (pollPeriod)

This property specifies the length of time the adapter waits between polling periods.

Interval between polling periods details

Required Yes
Possible values Integers greater than or equal to 0.
Default 2000
Unit of measure Milliseconds
Property type Integer
Usage The poll period is established at a fixed rate, which means that if running the poll cycle is delayed for any reason ( if a prior poll cycle takes longer than expected to complete) the next poll cycle occurs immediately to make up for the lost time caused by the delay.
Globalized No
Bidi supported No


Maximum events in polling period (pollQuantity)

This property specifies the number of events the adapter delivers to the export during each poll period.

Maximum events in polling period details

Required Yes
Default 10
Property type Integer
Usage The value must be greater than 0. If this value is increased, more events are processed per polling period and the adapter may perform less efficiently. If this value is decreased, fewer events are processed per polling period and the adapter's performance might improve slightly.
Globalized No
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


Port number property (portNumber)

Port number of the FTP server through which the connection is established during inbound processing.

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


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 No default value
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)

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


Remote archive directory property (ftpArchiveDirectory)

Relative path of the archive directory on the FTP server. The directory must exist. There are several options for using this property to specify archiving:

The value of remote archive 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.

Remote archive directory property characteristics

Required No
Default No default value
Property type String

Usage

You can use a WAS environment variable to represent the remote archive directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${REMOTEARCHIVE_DIRECTORY}. See Defining WAS environment variables.

The archive directory located on the FTP server and used in inbound configuration represents the absolute path of the archive directory. It does not contain any host name or URL information. This directory is located on the same FTP server where the Event Directory is located, for example: /home/archive.

The FTPArchiveDirectory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically.

Globalized Yes


Remote directory property (eventDirectory)

Remote directory of the FTP server from where the event files are retrieved for inbound processing. If the value of Remote directory is set to <HOME_DIR>, the adapter polls for event files in the users home directory.

The value of event 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 users home directory.

Remote directory property characteristics

Required Yes
Default <HOME_DIR>
Property type String
Usage

You can use a WAS environment variable to represent the remote directory. Set the name of the environment variable in braces, preceded by a $ symbol. For example: ${REMOTE_DIRECTORY}. See Defining WAS environment variables.

The EventDirectory must be created manually, on the machine where the adapter runs, before the adapter is started, as the adapter does not create this directory automatically. The adapter must have the right access permissions to delete the files on the event directory.

Globalized Yes


Verify remote directory access permission (isPermissionCheckEnabled)

This property specifies the access permissions for the event directory must be verified before performing the inbound operation.

Verify remote 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 event directory before performing the inbound 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 event directory, the inbound 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 event 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


Retrieve files with this pattern property (eventFileMask)

Filter for the event files. The file filter is a well-qualified expression consisting of alphanumeric characters and the * and ? wild cards.

Retrieve files with this pattern property characteristics

Required Yes
Default *.*
Property type String
Globalized Yes


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.

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

Globalized No
Bidi supported No


Retry EIS connection on startup (retryConnectionOnStartup)

This property controls whether the adapter attempts to connect again to the FTP server if it cannot connect at startup.

Retry EIS connection on startup details

Required No
Possible values

True False

Default False
Property type Boolean
Usage This property indicates whether the adapter should retry the connection to the FTP server if the connection cannot be made when the adapter is started:

  • Set the property to False when you want immediate feedback about whether the adapter can establish a connection to the FTP server, for example, when you are building and testing the application that receives events from the adapter. If the adapter cannot connect, the adapter writes log and trace information and stops. The administrative console shows the application status as Stopped. After you resolve the connection problem, start the adapter manually.

  • Set the property to True if you do not need immediate feedback about the connection. If the adapter cannot connect during startup, it writes log and trace information, and then attempts to reconnect, using the RetryInterval property to determine how frequently to retry and the value of the RetryLimit property to retry multiple times until that value is reached. The administrative console shows the application status as Started.

Globalized No
Bidi supported No


Time between retries in case of system connection failure (retryInterval)

When the adapter encounters an error related to the inbound connection, this property specifies the length of time the adapter waits before trying to reestablish a connection.

Retry interval details

Required Yes
Default 2000
Unit of measure Milliseconds
Property type Integer
Usage Only positive values are valid. When the adapter encounters an error related to the inbound connection, this property specifies the length of time the adapter waits before trying to establish a new connection.
Globalized No
Bidi supported No


Maximum number of retries in case of system connection failure (retryLimit)

This property specifies the number of times the adapter tries to reestablish an inbound connection.

Maximum number of retries in case of system connection failure

Required No
Possible values 0 and positive integers
Default 0
Property type Integer
Usage

This property controls how many times the adapter retries the connection if the adapter cannot connect to the FTP server to perform inbound processing. A value of 0 indicates an infinite number of retries.

To control whether the adapter retries if it cannot connect to the FTP server when it is first started, use the RetryConnectionOnStartup property.

Globalized No
Bidi supported 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


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 (socksProxyHost)

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

Host name property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Password property (socksProxyPassword)

Password used to authenticate the proxy server.

Password property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Port number property (socksProxyPort)

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


User name property (socksProxyUserName)

User name used to authenticate the proxy server.

User name property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Sort event files property (sortEventFiles)

Determines the sorting order of event files being polled.

Sort event files property characteristics

Required No
Possible values

  • by file name – sort ascending on file name
  • by time stamp – sort ascending on last modified timestamp
  • no sort – not sorted

Default no sort (= not sorted)
Property type String
Usage Event file ordering from which events need to be delivered is valid only if the activation specification deliveryType property is set to ORDERED. File name sorting is provided based on the locale of the FTP server. The ICU4J package is used to track the locales and their corresponding rules.

In a HA Active-Active configuration, sorting of event files being polled is not supported.

Globalized No


Specify criteria to split file content property (splitCriteria)

This property accepts different values based on the value of the splittingFunctionClassName property. For example: To specify that a file is to be split every 5 KB, set the splitCriteria property to 5000.

This property is disabled if the Pass only file name and directory, not the content property is selected.

When filePassByReference is enabled during inbound PassThrough, the event file is not split.

For input files that contain multiple COBOL copybook records, in order to enable file splitting by size you must provide the correct length of each record. To determine the size of each record, use one of these methods:

  1. Open the Business Object in a text editor.

    1. For example: 
      <element name="CustomerNumber">
<annotation>
<appinfo source="http://www.ibm.com/cam/2005/typedescriptor">
<td:typeDescriptorElement>
<td:initialValue kind="SPACE"/>
<td:simpleInstanceTD accessor="readWrite" attributeInBit="false" contentSize="5" offset="0" size="5">
<td:sharedType>
<td:stringTD addrUnit="byte" alignment="byte" characterSize="1" lengthEncoding="fixedLength" paddingCharacter=" " prefixLength="0" width="5"/>
</td:sharedType>
</td:simpleInstanceTD>
</td:typeDescriptorElement>
</appinfo>
</annotation>
<simpleType>
   <restriction base="string">
    <maxLength value="5"/>
  </restriction>
 </simpleType>
</element>
      Each element in the business object has a corresponding <element> entry.
    2. Look for a restriction tag for each element tag (the COBOL data binding requires a fixed-width data handler).

    3. Add up the maxLength attribute values for each of the elements. In this example, the value is 5. The sum of the maxLength values is the size of each record of type DFHCOMMAREA.

  2. Open the Business Object in a text editor.

    1. Look for the complex type tag with the business object name value in the name attribute. In the example that follows, the business object name is DFHCOMMAREA.

    2. Locate a namespace-appended tag called aggregateInstanceTD and use the value for the attribute contentSize. In this example, the value is 117. This is the size of each record of type DFHCOMMAREA. 
      <complexType name="DFHCOMMAREA">
<annotation>
<appinfo source="http://www.ibm.com/cam/2005/typedescriptor">
<td:typeDescriptorCT>
<td:aggregateInstanceTD accessor="readWrite" attributeInBit="false" contentSize="117" offset="0" size="117">

Specify criteria to split file content property characteristics

Required No
Default 0
Property type String
Globalized Yes


Splitting function class name property

This value accepts the fully qualified class name of the class file to be used to enable file splitting. The following are the class names the property can accept:

Optionally, you can provide a custom file splitter class and use it by inputting the class name into the splittingFunctionClassName property.

The delimiter or file size is provided in the splitCriteria property. If the splittingFunctionClassName property is null, this property is automatically set to com.ibm.j2ca.utils.filesplit.SplitBySize.

This property is disabled if the Pass only file name and directory, not the content property is selected.

Splitting function class name property characteristics

Required No
Default com.ibm.j2ca.utils.filesplit.SplitBySize
Property type String
Globalized No


Stop the adapter when an error is encountered while polling (stopPollingOnError)

This property specifies whether the adapter will stop polling for events when it encounters an error during polling.

Stop the adapter when an error is encountered while polling details

Required No
Possible values

True False

Default False
Property type Boolean
Usage

If set to True, the adapter stops polling when it encounters an error.

If set to False, the adapter logs an exception when it encounters an error during polling and continues polling.

Globalized No
Bidi supported No


Success file extension for local archive property (successArchiveExt)

File extension used to archive all the successfully processed business objects. This property is used only when localArchiveDirectory is valid and exists. For example, 12345.order > 12345.order.success

Success file extension for local archive property characteristics

Required No
Default success
Property type String
Globalized Yes


Time out period for HA Active-Active event processing change (in seconds) (EP_Timeout)

Specifies the time interval, in seconds, for processing the events fetched. The unprocessed events at the end of the time interval are reprocessed as new events.

Time out period for HA Active-Active event processing change (in seconds) property characteristics

Required Yes
Default 300
Unit of measure Seconds
Property type Integer
Usage This property is used for specifying the time interval, in seconds, for the adapter to process the events fetched. If for any reason the adapter fails to process all the fetched events at the end of the time interval, the unprocessed events are reprocessed as new events by a different adapter.

You can use this property if the HA Active-Active configuration is enabled and the guaranteed delivery event is required.

The minimum value for this property is 0. If you set a value less than 0, an error message appears

Globalized No
Bidi supported No


User name property (userName)

Name of the user who has privileges to connect to the FTP server and perform FTP operations. You do not need to specify a value for this property if the user name is included in the URL specified in the eventDirectory property.

User name property characteristics

Required No
Default No default value
Property type String
Globalized Yes


User name used to connect to event data source property (EP_UserName)

User name used by event persistence for getting the database connection from the data source.

User name used to connect to event data source property characteristics

Required No
Default No default value
Property type String
Globalized Yes


Rule editor to filter files (ruleTable)

This property is used to filter event files based on a set of rules

Rule editor to filter files

Required Optional
Default No default value
Property type String
Usage During an inbound processing, if the value in the rule table is specified, then the event files are fetched after filtering, based on the specified rules before polling those event files.
Globalized Yes
Bidi supported No



Related tasks:

Generating the service

Feedback


Globalization

WebSphere Adapter for FTP is a globalized application that can be used in multiple linguistic and cultural environments. Based on character set support and the locale of the host server, the adapter delivers message text in the appropriate language. The adapter supports bidirectional script data transformation between integration components.



Related tasks:

Generating the service

Feedback


Globalization and bidirectional transformation

The adapter is globalized to support single- and multi-byte character sets and deliver message text in the specified language. The adapter also performs bidirectional transformation, which refers to the task of processing data that contains both left-to-right (Hebrew or Arabic, for example), and right-to-left (a URL or file path, for example) semantic content within the same file.


Globalization

The Javaâ„¢ runtime environment within the Java virtual machine (JVM) represents data in the Unicode character code set. Unicode contains encodings for characters in most known character code sets (both single- and multi-byte). Components in the WebSphere Business Integration system are written in Java. Therefore, when data is transferred between WebSphere Business Integration system components, there is no need for character conversion.

To log error and informational messages in the appropriate language and for the appropriate country or region, the adapter uses the locale of the system on which it is running.


Bidirectional transformation

Languages such as Arabic and Hebrew are written from right to left, yet they contain embedded segments of text that are written left to right, resulting in bidirectional script. When software applications handle bidirectional script, standards are used to display and process it. IBM Business Process Manager and WebSphere Enterprise Service Bus use the Windows standard format, but an enterprise information system exchanging data with BPM or WebSphere Enterprise Service Bus can use a different format. WebSphere Adapters transform bidirectional script data passed between the two systems so that it is accurately processed and displayed on both sides of a transaction.

Bidirectional format

IBM Business Process Manager and WebSphere Enterprise Service Bus use the bidirectional format of ILYNN (implicit, left-to-right, on, off, nominal). This is the format used by Windows. If an enterprise information system uses a different format, the adapter converts the format before introducing the data to IBM Business Process Manager or WebSphere Enterprise Service Bus.

The bidirectional format consists of five attributes. When you set bidirectional properties, you assign values for each of these attributes. The attributes and settings are listed in the following table.

Bidirectional format attributes

Letter position Purpose Values Description Default setting
1 Order schema I Implicit (Logical) I
V Visual
2 Direction L Left-to-Right L
R Right-to-Left
C Contextual Left-to-Right
D Contextual Right-to-Left
3 Symmetric Swapping Y Symmetric swapping is on Y
N Symmetric swapping is off
4 Text Shaping S Text is shaped N
N Text is not shaped (Nominal)
I Initial shaping
M Middle shaping
F Final shaping
B Isolated shaping
5 Numeric Shaping H National (Hindi) N
C Contextual shaping
N Numbers are not shaped (Nominal)

The adapter transforms data into a logical, left-to-right format before sending the data to IBM Business Process Manager or WebSphere Enterprise Service Bus.

Use bidirectional properties

You can use multiple bidirectional properties to control the transformation of both content data and metadata. You can set special bidirectional properties to exclude either content data or metadata from bidirectional transformation, or to identify data that requires special treatment during a transformation.

The following table describes four types of bidirectional properties.

Bidirectional property types

Property type Data transformations
EIS Controls the format for content data, or data that is sent by the enterprise information system.
Metadata Controls the format for metadata, or data that provides information about the content data.
Skip Identifies content or metadata to exclude from transformation.
Special Format Identifies certain text, such as file paths or URLs, that require different treatment during the transformation process. Can be set for either content data or metadata.

You can set properties that control bidirectional transformation in three areas.

Business object annotations

Some adapters allow you to annotate bidirectional properties within a business object. Do this to add information that specifically controls the transformation of a business object or part of a business object. Use business object editor, a tool within IBM Integration Designer, to add annotations at these levels:

Property scope and lookup mechanism

After you set values for bidirectional properties for an adapter and annotate business objects where appropriate, the adapter performs bidirectional transformations. It does so by using logic that relies on a hierarchical inheritance of property settings and a lookup mechanism.

Properties defined within the resource adapter are at the top of the hierarchy, while those defined within other areas or annotated within a business object are at lower levels of the hierarchy. So for example, if you only set values for EIS-type bidirectional properties for the resource adapter, those values are inherited and used by transformations that require a defined EIS-type bidirectional property whether they arise from an inbound (activation specification) transaction or an outbound (managed connection factory) transaction.

However, if you set values for EIS-type bidirectional properties for both the resource adapter and the activation specification, a transformation arising from an inbound transaction uses the values set for the activation specification.

The processing logic uses a lookup mechanism to search for bidirectional property values to use during a transformation. The lookup mechanism begins its search at the level where the transformation arises and searches upward through the hierarchy for defined values of the appropriate property type. It uses the first valid value it finds. It searches the hierarchy from the child object to the parent object only; siblings are not considered in the search.



Related reference:

Properties enabled for bidirectional data transformation

Activation specification properties

Managed (J2C) connection factory properties

Feedback


Bidirectional transformation in business objects

For outbound processing, you can modify the business objects to enable the bidirectional transformation of the wrapper properties in the WebSphere Adapter for FTP business object and the data in content-specific or generic business objects.

You have to add an annotation to the complex type of the business object to specify the bidirectional formatting attributes in the files for the following business objects:

The following sections include annotations that can serve as examples.


Bidirectional formatting attributes of the business object

The following annotation, which contains the bidirectional context information, applies to all the attributes in the FTP business objects. The FTPFileBaseDataBinding uses the bidirectional information in the element BiDiContext to transform all the attributes. 

<xsd:complexType name="Customer">
<xsd:annotation>
            <xsd:appinf
                source="http://www.ibm.com/xmlns/prod/websphere/j2ca/datatransformation/databindingm
apping">
                <dtm:DataBindingMapping
                    xsi:type="dtm:DataBindingMapping"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xmlns:dtm="http://www.ibm.com/xmlns/prod/websphere/j2ca/datatransformation/databindingmapping">                  
                    <BiDiContext>
                            <orientation>rtl</orientation>
                            <textShape>nominal</textShape>
                            <orderingScheme>visual</orderingScheme>
                            <symmetricSwapping>true</symmetricSwapping>
                            <numeralShapes>nominal</numeralShapes>
                    </BiDiContext>
                </dtm:DataBindingMapping>
            </xsd:appinfo>
        </xsd:annotation>


Bidirectional formatting attributes of the wrapper

You can add an annotation to the wrapper of a user-defined type business object. The annotation in the wrapper business objects such as the generic (FTPFile) and the user-defined type (CustomerWrapper) is used to do bidirectional transformation of wrapper attributes. The content-specific business objects that are used inside the wrapper business objects are not transformed using annotation in the wrapper business objects. To transform content-specific business objects, edit the respective business object definition to add the annotation shown in the previous example for bidirectional formatting of attributes of the business object.

The following annotation is an example for the wrapper: 

<complexType name="CustomerWrapper">
<annotation>
            <appinfo
                source="http://www.ibm.com/xmlns/prod/websphere/j2ca/
datatransformation/databindingmapping">
                <dtm:DataBindingMapping
                    xsi:type="dtm:DataBindingMapping"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                    xmlns:dtm="http://www.ibm.com/xmlns/prod/websphere/j2ca/
datatransformation/databindingmapping">                  
                    <BiDiContext>
                            <orientation>rtl</orientation>
                            <textShape>nominal</textShape>
                            <orderingScheme>visual</orderingScheme>
                            <symmetricSwapping>true</symmetricSwapping>
                            <numeralShapes>nominal</numeralShapes>
                    </BiDiContext>
                </dtm:DataBindingMapping>
            </appinfo>
        </annotation>


Feedback


Properties enabled for bidirectional data transformation

Bidirectional data transformation properties enforce the correct format of bidirectional script data exchanged between an application or file system and integration tools and runtime environments. After these properties are set, bidirectional script data is correctly processed and displayed in IBM Integration Designer and IBM Business Process Manager or WebSphere Enterprise Service Bus.


Managed (J2C) connection factory properties

The following managed (J2C) connection properties control bidirectional transformation.


Activation specification properties

The following activation specification properties control bidirectional transformation.


Deployment Descriptor configuration properties

The following Deployment Descriptor configuration properties control bidirectional transformation.


Wrapper business object properties

The following wrapper business object properties control bidirectional transformation.



Related concepts:

Globalization and bidirectional transformation

Feedback


Adapter messages

View the messages issued by WebSphere Adapter for FTP at the following location.

Link to messages: Adapter messages

The displayed Web page shows a list of message prefixes. Click a message prefix to see all the messages with that prefix:


Feedback


Related information

The following information centers, IBM Redbooks , and web pages contain related information for WebSphere Adapter for FTP.


Information resources


Information about related products


developerWorks resources


Feedback


12. Adapter documentation in PDF format

Documentation in PDF format for WebSphere Adapter for FTP is available at the following location.

Adapter documentation in PDF format: ftp://ftp.software.ibm.com/software/websphere/integration/wsa/library/pdf7503/


Feedback


+

Search Tips   |   Advanced Search