IBM BPM, V8.0.1, All platforms > Authoring services in Integration Designer > Services and service-related functions > Access external services with adapters > Configure and using adapters > IBM WebSphere Adapters > FTP > Configure the module for deployment > Configure the adapter for inbound processing

Setting deployment and runtime properties

Specify deployment and runtime properties that 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 Starting 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.

Procedure

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. Specify 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.

   • Event polling configuration

     1. In the Interval between polling periods field, specify the number of milliseconds that the adapter must wait between polling periods. See Interval between polling periods (pollPeriod).

     2. In the Maximum events in polling period field, specify the number of events that the adapter must deliver in each polling period. See Maximum events in polling period (pollQuantity).

     3. In the Time between retries in case of system connection failure field, specify the number of milliseconds for the adapter to wait before trying to connect after a connection failure during polling. See Time between retries in case of system connection failure (retryInterval).

     4. In the Maximum number of retries in case of system connection failure field, specify the number of times to retry the connection before reporting a polling error. For more information, see Maximum number of retries in case of system connection failure (retryLimit).

     5. If you want the adapter to stop if polling errors occur, select Stop the adapter when an error is encountered while polling.

        If you do not select this option, the adapter logs an exception but continues to run. See Stop the adapter when an error is encountered while polling (stopPollingOnError).

     6. Select Retry EIS connection on startup if you want the adapter to retry a failed connection when starting. See Retry EIS connection on startup (retryConnectionOnStartup).

     7. In the Time interval for polling unchanged files field, specify the time interval for which the adapter needs to monitor the files for any updates in the content before polling. The adapter polls those files that are not changed during the specified time interval. See Time interval for polling unchanged files (fileUnchangedTimeInterval).
     8. Polling based on business calendar

        Select the calendar based scheduling option to create calendar based polling for inbound activities.

        You can schedule your business activities, when you create a new calendar in IBM Integration Designer. The option of working with the calendar based scheduling feature is only possible with IBM Integration Designer as the tooling environment. The following figure helps you to schedule a calendar polling option.

        Figure 3. Polling based on business calendar

        

        You can either select a blank calendar or create a new calendar for a module or library.

        When you select a blank calendar, you will not be able to set predefined time intervals. You have to define your time intervals. When you create a calendar using a predefined template, you can define time intervals for each template.

        • To select an existing calendar for a module or library, click Browse. In the Select a Business Calendar window, you can search for existing calendar files ( *cal) in the IBM Integration Designer workspace.

          1. In the Filter by name field, type the calendar name or name pattern. The calenders matching the pattern are displayed in the Matching business calendars area.

          2. Select a calendar and click OK to return to the external service wizard.

        • To create a new calendar entry for a module or library, click New. The Create a business calendar window is displayed.

          1. In the Module or library field, click Browse to select an existing calendar module or click New to create a module for the new calendar.

          2. In the Folder field, click Browse to select an existing folder or create a new folder for the calendar.

          3. In the Name field, enter a name for the new calendar.

             • To create a non template calendar, click Finish. Or

             • To generate the calendar based on a predefined template, click Next. In the Use a template window, select the Create a calendar using one of the templates check box and click Finish.

             The new business calendar is created and available in the Business Integration view. Once you complete the wizard, you can view or modify the calendar schedules in the Business Integration view using the Business Calendar Editor. You can modify the intervals and exceptions, or add new entries for these elements. For more details about working with business calendars, see Business calendars.

        You must deploy the Business Calendar module to the same IBM BPM or WebSphere Enterprise Service Bus instance, along with the inbound application. If you do not map these two connections to the same server instance, the inbound application using the business calendar will by default, poll as there is no calendar configured.

   • Event delivery configuration

     1. In the Type of delivery field, select the delivery method. The methods are described in Delivery type (deliveryType).

        HA Active-Active configuration supports only unordered delivery type events. If the delivery type is ORDERED, then a runtime exception error occurs.

     2. If you want to ensure that events are delivered only once and to only one export, select Ensure assured-once event delivery. This option might reduce performance but does not result in duplicate or missing an event delivery. See Ensure once-only event delivery (assuredOnceDelivery).

     3. In the Retry limit for failed events field, specify the number of times that the adapter must attempt to redeliver an event before marking it as failed. See Retry limit for failed events (failedEventRetryLimit).
   • Event persistence configuration

     In a HA Active-Active configuration, ensure that you provide values for all the mandatory event persistence properties. If the value is not assigned to any of the event persistence properties, a runtime exception occurs.

     1. Select Auto create tables (Supports IBM DB2, Oracle, Apache Derby, Microsoft SQL Server) if you want the adapter to create the Event Persistence table and the File table. See Auto create tables property (EP_CreateTable).

     2. In the Table name to store the event persistence information field, specify the name of the table that the adapter uses for event persistence. See Table name to store the event persistence information property (EP_TableName).

     3. In the Table name to store the file processing status field, specify the name of the table that the adapter uses for file processing. See Table name to store the file processing status (EP_FileTableName).

     4. In the Event recovery data source (JNDI) name field, specify the JNDI name of the data source that event persistence uses to connect to the JDBC database. See Event recovery data source (JNDI) name property (EP_DataSource_JNDIName).

     5. Optional: In the User name used to connect to event data source field, specify the user name that the event persistence uses to connect to the database from the data source. See User name used to connect to event data source property (EP_UserName).

     6. Optional: In the Password used to connect to event data source field, specify the password that the event persistence uses to connect to the database from the data source. See Password used to connect to event data source property (EP_Password).

     7. Optional: In the Database schema name field, specify the schema name of the database that the event persistence uses. See Database schema name property (EP_SchemaName).

     8. In the Time out period for HA Active-Active event processing change (in seconds) field, specify the time interval for the adapter to process the events fetched. See Time out period for HA Active-Active event processing change (in seconds) (EP_Timeout).

   • Additional configuration

     1. In the Retrieve files with this pattern field, specify the filter for the event files. See Retrieve files with this pattern property (eventFileMask).

     2. In the Sort event files field, specify the sorting order of the event files being polled. See Sort event files property (sortEventFiles).

        In a HA Active-Active configuration, sorting of event files is not supported.

        If the default value ( no sort) is changed, then a runtime exception occurs.

     3. Select the Enable remote verification check box to enable remote verification. This property checks if the control and data connections are established with the same host (typically, the machine from which you establish a connection to the FTP server). The connection fails if the control and data connections are not established. By default, the Enable remote verification check box is selected.

        This property is applicable only to FTP and FTPS protocols. See Enable remote verification property (enableRemoteVerification).

     4. In the Encoding used by FTP server field, specify the encoding of the FTP server. See Encoding used by FTP server property (EISEncoding).

     5. In the File content encoding field, specify the encoding used to read the event files. See File content encoding property (fileContentEncoding).

     6. In the FTP server connection mode field, specify the data connection mode used by the FTP server during file transfers. See FTP server connection mode property (dataConnectionMode).

     7. In the File transfer type field, specify the file transfer type used during inbound processing. See File transfer type property (fileTransferType).

     8. In the Number of files to get at a time field, specify the number of files retrieved from the remote FTP URL. See Number of files to get at a time property (ftpGetQuantity).

     9. In the Number of poll periods between downloads field, specify how frequently the adapter polls the FTP server. For more information, see Number of poll periods between downloads property (ftpPollFrequency).

     10. In the Custom parser class name field, click Browse to specify the fully qualified class name of the custom parser used to parse the ls output. See Custom parser class name property (customParserClassName).

     11. Select Pass only file name and directory, not the content to specify that the file content of the event file is not sent to the export. See Pass only file name and directory, not the content property (filePassByReference).

         You cannot select this property if the Split file content based on the size (bytes) or delimiter property is selected.

     12. Select Include business object delimiter in the file content to specify that the delimiter will be sent with the business object content for further processing. See Include business object delimiter in the file content property (includeEndBODelimiter).

     13. Select Include total business object count in the ChunkInfo property to specify that the total business object count will be included in the chunk information of the dataobject sent to the endpoint. See Include total business object count in the ChunkInfo (includeBOCountInChunkInfo).

     14. Select Split file content based on the size (bytes) or delimiter to use the size in bytes or the delimiter to split the file content. See Splitting function class name property.

         You cannot select this property if the Pass only file name and directory, not the content property is selected.

     15. In the Specify criteria to split file content field, specify that different values will be taken, based on the value of the SplittingFunctionClassName property. See Specify criteria to split file content property (splitCriteria).

     16. In the Split function class name field, specify the fully qualified class name of the class file to be used to enable file splitting. See Splitting function class name property.

     17. In the Run FTP script file before downloading files field, specifies the path of the script file that will be executed before downloading the files from the FTP server. See Run FTP script file before downloading files property (ftpScriptFileExecutedBeforeInbound).

     18. In the Run FTP script file after downloading files field, specifies the path of the script file that will be executed after downloading the files from the FTP server. See Run FTP script file after downloading files property (ftpScriptFileExecutedAfterInbound).
   • FTP archiving configuration

     1. In the Local archive directory field, specify the absolute path of the local Archive directory. See Local archive directory property (localArchiveDirectory).

     2. In the File extension for local archive field, specify the file extension used to archive the original event file. See File extension for local archive property (originalArchiveExt).

     3. In the Success file extension for local archive field, specify the file extension used to archive all the successfully processed business objects. See Success file extension for local archive property (successArchiveExt).

     4. In the Failure file extension for local archive field, specify the file extension used to archive business objects in the event file that are not successfully processed. See Failure file extension for local archive property (failedArchiveExt).

     5. In the Remote archive directory field, specify the directory. See Remote archive directory property (ftpArchiveDirectory).

     6. In the File extension for remote archive field, specify the file extension or suffix that the adapter uses to rename the remote FTP file. See File extension for remote archive property (ftpRenameExt).
   • Socks proxy server connection information

     1. In the Host name field, specify the host name of the machine used as a proxy server through which the adapter requests are routed to the FTP server. See Host name property (socksProxyHost).

     2. In the Port number field, specify the port number of the proxy server through which the adapter requests are routed to the FTP server. See Port number property (socksProxyPort).

     3. In the User name field, specify the user name for authenticating the proxy server. See User name property (socksProxyUserName).

     4. In the Password field, specify the password used to authenticate the proxy server. See Password property (socksProxyPassword).
   • Secure configuration

     1. If you want to compare the host key of the SFTP server with the host keys known to the adapter:

        1. Select the Enable remote server authentication for SFTP protocol check box. The host key file has to be available with the host keys of the trusted server before the first attempt to connect to SFTP server is made. See Enable server verification property (EnableServerVerification).

        2. In the Host key file field, specify the absolute file path to the host key file. The host key file is created by the administrator and contains the host keys of all the trusted servers. The Host key file property points to the file on the adapter workstation. See Host key file property (HostKeyFile).

     2. If you want to enable public key authentication, specify the following properties:

        1. In the Private key file field, specify the private key used to authenticate to the Secure shell server. See Private key file property (privateKeyFilePath).

        2. In the Passphrase field, specify the phrase used for enhanced security by encrypting the private key. For more information, see Passphrase property (Passphrase).

     3. Specify the following properties for the FTPS protocol:

        1. In the FTPS connection mode field, specify the connection mode (Implicit or Explicit) to connect to the FTPS server, when FTPS is selected as protocol. See FTPS connection mode property (ftpsConnectionMode).

        2. In the Data channel protection level field, select the level of the data channel protection that you want to use:

           • Select Private, if the data transfer between the Adapter and the FTPS server has to be in an encrypted form.

           • Select Clear, if the data transfer between the Adapter and the FTPS server has to be in clear text form.

             See Data channel protection level (dataProtectionLevel).

        3. In the Keystore type field, specify type of the keystore. See Keystore type property (keyStoreType).

        4. In the Truststore file field, specify the path of the truststore file that contains the certificates of the servers trusted by the adapter. See Truststore file property (trustStorePath).

        5. In the Truststore password field, specify the password of the truststore file. It is used to check the integrity of the truststore data. If this value is not specified, the integrity check will not be performed. See Truststore password property (trustStorePassword).

        6. In the Keystore file field, specify the path of the keystore file. The Keystore file contains the private key entry of the FTPS client and also contains a certificate chain for the corresponding public key. See Keystore file property (keyStorePath).

           Both Keystore file and Truststore file properties share the properties of Keystore type.

        7. In the Keystore password field, specify the password of the keystore. It is used to check the integrity of the keystore data. If this value is not specified, integrity check will not be performed. See Keystore password property (keyStorePassword).

        8. In the Key password field, specify the password of the key used to recover the keys from the keystore. See Key password property (keyPassword).
   • Bidi properties

     • In the Bidi properties area, select Bidi transformation.
     • Set the ordering schema, text direction, symmetric swapping, character shaping, and numeric shaping properties to control how bidirectional transformation is performed.

   • Logging and tracing

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

     2. Select Disguise user data as 'XXX' in log and trace files if you want to prevent sensitive user data from being written to log and trace files. See Disguise user data as "XXX" in log and trace files (HideConfidentialTrace).

6. Specify 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. Specify 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.

        If you want 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.

Results

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

What to do next

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.

Configure the module for inbound processing

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