Modify an FTP (external) pickup or delivery

After you create an external FTP pickup or delivery, you view and modify the fields that define the object.

FTP or FTPS settings tab (pickup and delivery)

• FTP Server – The network name of the FTP server.
• Port – The port on which the server listens for incoming connections. The default is 21 (embedded FTP default is 4021).
• User name – The user name to connect to the server.
• Password – The password to connect to the server.
• Confirm password – The password to connect to the server.
• Select the file type – From the drop-down list, select the format of the files that are transmitted over this delivery:
  • Binary (default)
  • ASCII - automatic line ending
  • ASCII - user CR/LF
  • ASCII - use LF only
• In most cases, use binary mode, (default). Always trade packaged files (for example, AS2, AS3, Secure file) in binary mode.
• Use binary mode also for trading text files. This applies to text files with no packaging if the receiver is not sensitive to the type of line-ender. If the receiver requires a particular line-ender, select an ASCII option to have Activator translate the line-ender based on what is required by the back-end system.
• Three ASCII options are available for pickup exchanges, but only one for delivery exchanges. The FTP specification requires the sender to always use CRLF as the line-ender when transmitting files in ASCII mode. It is up to the receiver to translate the line-ender to something else if desired.
• Use passive mode (delivery only) – Select this option to transmit files using passive mode. In this mode, during the connection, the server specifies the port it will listen to for the data connection.
  
• Use active mode (delivery only) – Select this option to transmit files using active mode. Then in the Active ports field, enter the ports where the client will listen to the data port of the server.
• Note: To configure Activator to connect to a partner's embedded FTPS server in active mode, you must add the public key of the client server as a trusted SSL root certificate on the FTPS embedded server used for the pickup/delivery exchange.
• Clients must use SSL to connect to this server – Select this option to have Secure Sockets Layer protocol in use during connections. The server presents a certificate for verification. To do this, a certificate in a Community or Partner definition must be designated as the SSL certificate. The server must support SSL. If this option is not selected, connections are not encrypted.
• Enable host name verification – If selected, Activator compares the name of the SSL server to the name in the server’s certificate to ensure they are the same.
• Use Implicit SSL – Select this option if you want to use implicit SSL rather than explicit SSL (which is the default mode). FTP supports two methods to accomplish security through a sequence of commands passed between two computers. The sequence is initiated with explicit (active) or implicit (passive) security.
  • Explicit security – To establish the SSL link, explicit security requires the FTP client to issue a specific command to the FTP server after establishing a connection. The default FTP server port is used.
  • Implicit security – Implicit security begins with an SSL connection as soon as the FTP client connects to an FTP server. The FTP server defines a specific port for the client to be used for secure connections. Not all FTP servers support implicit security. Check the documentation for your server.

Directories tab (pickup and delivery)

• Pickup directory – Type the path of the directory on your server where messages are picked up. When Activator polls the server for files, it only looks in the pickup directory, not an inbox directory. If connecting to a partner’s Activator-embedded FTP server, use mailbox if picking up. Leave the field blank if delivering.
• Use temporary files to avoid read/write collisions – We recommend using this option to prevent Activator from attempting to retrieve partially written files. When this is selected, you must select one of the two following options.
• There may be some specialized servers, typically running on mainframes, that support only part of the FTP protocol (RFC 959). In such cases you may have to clear this option and take steps of your own to make sure collisions do not occur.
• If connecting to a partner’s Activator-embedded FTP server, clear the check box.
  • Use separate directory for temporary files – Type the full path of an inbox directory (for example, c:\data\inbox). Files are uploaded to this directory. When fully written, files are moved to the pickup directory for retrieval.
  • Do not put the inbox under the pickup directory unless you use a period at the beginning of the inbox name. Activator and other applications ignore directories and files that begin with periods.
  • For example, do not use the following directory structure:
  • c:\data\pickup\inbox
  • But you can use the following because a period is the first character of the inbox directory name:
  • c:\data\pickup\.inbox
  • When receiving files from a partner, we recommend that your partner write files to the inbox directory first and then move them to the pickup directory when they are ready to be retrieved. This process is automatic if your partner also uses Axway products B2Bi, Interchange or Activator. If the partner uses other software to upload files to your server, the software should be configured to initially upload the files to the inbox directory and move them to the pickup directory when they are ready to be retrieved.
  • For outbound integration, the back-end system must write the message to the inbox and then move it to the pickup directory.
  • For inbound integration and sending outbound to partners, Activator writes to the inbox and then moves the message to the pickup directory.
  • Use special extension in pickup directory for temporary files – If you prefer not to use an inbox, select this option. While a file is being written to the pickup directory, a temporary extension is added so the system knows not to retrieve it because the file is only partially written. Once fully written, the temporary extension goes away and the file can be retrieved.
• Attempt restarts – Indicates whether the system resumes transferring large files at the point interrupted when a connection is lost before a transfer is completed. If you select this check box, the system resumes processing of files at least as large as specified in the restartable minimum bytes field. This checkpoint-restart feature is worthwhile only for large documents. If this option is not used, the system starts a file transfer over when processing is interrupted.
  • Restartable minimum bytes (MB) – If attempt restarts is selected, the minimum size of a file that triggers the system to continue the file transfer at the point interrupted before the connection was lost. The minimum size is in megabytes. The system only resumes transfers of files that meet this minimum. The system starts over the transfer of smaller files whose processing is interrupted.
  • Temporary file lifetime (hours) – If attempt restarts is selected, how long the system retains a file whose transfer has been interrupted while waiting for the connection to be restored. This temporary file enables the system to resume the transfer at the point interrupted.

Filenames tab (delivery)

Delivery file name definition

• Preserve original filenames – (default) Select this option if you want the original file names to be preserved when Activator delivers messages.
• Preserving original file names enables your back-end application to process binary messages based on their file names.
• Generate unique filenames – Select this option to have the system provide a unique file name (instead of using the original name).
  • Automatically generate unique filenames – Activator appends to the file name a hex representation of a monotonically increasing file name counter that is maintained in the database. Names are guaranteed to be unique. In addition, if the original file name had an extension, the same extension is appended to the unique name the system generates.
  • Example with the original file extension:
  • dabeed45_4cb.edi
  • Example without the original file extension:
  • z47e4120_4ce
  • Define custom filename construction – Activator generates a file name using a pattern that you specify. Enter the pattern in the Pattern field.
  • For additional information about entering renaming patterns, see File renaming patterns.

Duplicate file name handling

• Overwrite duplicate filenames – If Activator detects a duplicate file name, it overwrites the existing file, replacing it with the duplicate file.
• Sequentially number duplicate filenames – (default) When you select this option you must also select a name generation option:
  • Automatically generate unique filenames – (default). If Activator detects a duplicate file name, it generates a sequentially numbered file name. Activator appends a number to the new file in the format: filename_c4.
  • Define custom filename construction – Activator generates a file name using a pattern that you specify. Enter the pattern in the Pattern field.
  • For additional information about entering renaming patterns, see File renaming patterns.
• Append to existing files – Append the duplicate file content to the content of the original file.

File name security (external FTP servers only)

• Make output filenames safe for all FTP servers by prefixing them with a letter if they start with numbers, and by applying the regular expressions in filenamebeautifier.xml – (For external FTP servers only) Select this option to have Activator add a letter prefix to file names that begin with a numeral. This is for servers that cannot process files with names that begin with a numeral.

Advanced tab (pickup)

• Maximum concurrent connections (for trading pickups only)– The number of total open connections Activator can make to a partner.
• If you select the consumption order option "Process by timestamp" on this tab, the software automatically sets the value of this field to "1".
• Connect timeout (seconds) – Time in seconds Activator waits for a connection to the delivery exchange before the attempt times out. Although the default value is 30 seconds, this may be longer than the interval allowed by your operating system (OS). For example, Windows XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is the lesser of the OS timeout and the value set in Activator.
• Read timeout (seconds) – Time in seconds Activator waits to read data from the delivery exchange before terminating the connection.
• User commands – Enter user commands such as SITE to be sent to the server after login. Commands must be entered in the exact case and format expected by the server. For example, most FTP clients allow “mkdir test”, but most servers only accept “MKD test”. Consult RFC 959 for a list of standard FTP commands. You can use FTP commands that do not make use of the FTP data connection. Commands that make use of the FTP data connection are not supported. In addition, specific servers may support other commands. Refer to the server documentation for more information.
• If any command fails, the remaining commands are not executed, and production to the FTP server fails. To avoid possible failures, preface any command with an “at” sign (@) to indicate that errors from that command should be ignored, for example, “@MKD test”. Preface any command with an asterisk to cause the entire line to be treated as a comment, for example, “*Create test directory”.
• This field is available for the FTP transport only.
• Command set file key – The FTP command set file controls the commands sent to the FTP server for operations such as send, receive, delete. The default command set file is ftpcommandset.xml. This field lets you specify a different command set file. In most cases you can use the default value. Changing this is only for advanced FTP users with specialized needs.
• The field value is the name of an entry in filereg.xml in <install directory>\conf that points to another file in the conf directory. The following is the entry in filereg.xml for the default ftpcommandset.xml file:
• <File name="ftpcommandset.xml" path="conf/ftpcommandset.xml"/>
• If you want to add a new command set file, create the file and add an entry for it in filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter that name in the field and add the following entry to filereg.xml:
• <File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
• Delete file after it is downloaded – Select this if you want the server to delete files after they have been downloaded from it. This option should be enabled in most cases. Most servers do not delete files after clients have downloaded them. However, some servers do. If an external server automatically deletes files that have been downloaded, deselect this option. This option applies only to delivery exchanges using external FTP servers for picking up messages from the back end or receiving messages from partners.
• Enable file filtering – Available for some exchanges used for application pickups and for receiving from partners, file filtering allows Activator to discriminate which files to consume based on file names.
• In the file name filter pattern field, type the formats of the files you want the transport to consume or ignore. Use conventional wildcard characters for file names or extensions or both. The following describes the supported characters and symbols:

• *	One or more characters.
  ?	Any single character.
  [ ]	Matches any single character within the brackets. For example, r[aou]t matches rat, rot and rut.
  ,	Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
  -	Use hyphens within brackets to specify ranges of letters or numbers. For example, [0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-case letter.
  .	Use the character dot to separate the file name and extension. For example, *.txt.
  |	Use the pipe character to separate multiple file name formats. For example, *.edi|*.txt|[a,b,c]?.xml.

• Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive, only files matching the pattern are consumed. If exclusive, files matching the pattern are ignored, but all other files are consumed.
• Activator ignores files that do not meet filtering conditions. Ignored files are not reported in Message Tracker. Such files also do not generate log messages unless the following property is set to debug in conf\log4j.properties:
• log4j.category.com.cyclonecommerce.tradingengine
• Back up the files that go through this transport – Indicates whether the system backs up copies of the messages it retrieves from integration or receives from partners.
• Backing up files is strongly recommended. This is required for the system to perform fail-over operations such as attempting to send messages again (retries) in case of a transport connection failure. Without backups, a message in process cannot be recovered if the server stops or restarts. Backups also are needed if you want the ability to resubmit messages to back-end applications or resend messages to partners.
• Backup files are stored in \<install directory>\common\data\backup, unless you specify otherwise.
• Restrict maximum file size for this transport – Optionally lets you specify the maximum size of files a transport can handle. If Activator receives a file larger than the maximum, the file is rejected and a message is written to the events log. If received via HTTP, a 413 response also is sent and the connection is closed. A 413 message is Request Entity Too Large.
• The maximum size must be expressed in bytes. Do not use commas. For instance, a kilobyte is 1024 bytes, a megabyte is 1048576 bytes, a gigabyte is 1073741824 bytes.
• The smallest maximum allowed is 1000 bytes. On the opposite extreme, you can enter the largest number the field can accommodate.
• This control is available only for transports used for picking up messages from integration or receiving messages from partners.
• Polling configuration:
  • Maximum files per polling interval – The highest number of messages the system can retrieve each time it polls.
  • Polling interval (seconds) – The interval in seconds Activator waits before polling for messages to retrieve.
• Consumption order:
  • Allow server to determine – This is the default behavior. Activator processes messages in a random order.
  • Process by timestamp (oldest first)– Select this option if you want Activator to process messages in the order oldest-to-newest. The external FTP server must support the MDTM command.
  • If you select this option, the value of the field "Maximum concurrent connections" is automatically set to "1".
  • Note: In some cases setting concurrent connections to "1" may cause reduced throughput.
    
• Post-processing script – The full path to an executable file that contains post-processing commands. This field is available for community integration delivery exchanges and partner trading delivery exchanges.

• Specify preferred nodes – If there are one or more nodes for Activator, you can select one or more as the preferred nodes for consuming messages. If the preferred nodes are running, these are used to process messages. If the preferred nodes are stopped, work is distributed among the remaining running available nodes. Selecting preferred nodes lets you manage work distribution among nodes.
• This option is available for integration pickup and trading delivery exchanges that poll for messages.
• In general, this setting should not be used. Usually it is best to let Activator automatically determine which node should be responsible for initiating the polling of which exchange point.

Advanced tab (delivery)

• If sending messages to Transfer CFT via PeSIT, the value in this field must be less than the CFTTCP setting in Transfer CFT.
• This setting applies only to transports that send messages to partners or deliver messages to integration.
• Retries – This is the number of times Activator will retry connecting to the partner’s transport if the initial attempt to connect and send the message failed. The following are common reasons for triggering retries.
  • The connection attempt failed immediately for a reason such as host not found.
  • The host was found, but the connection process took longer than the connect timeout interval specified on the Advanced tab.
  • The connection was successful, but the partner’s HTTP server took longer than the response timeout interval to return a 200 OK response indicating the message was successfully received. A 200 OK response is a transport response, separate from a message protocol response such as an AS2 receipt.
• Note that in the last case, the 200 OK response also will include the receipt if synchronous receipts were requested. Otherwise, it will be a simple 200 OK response with no payload. And if an asynchronous receipt was requested, the partner will connect later to send it.
• Retries occur according to an algorithm that starts at 5 minutes. The interval between retries increases with each subsequent retry in this pattern: 10 minutes, 15 minutes, 30 minutes, 60 minutes. The interval plateaus at 60 minutes. This means if the retry value is greater than 5, the fifth and each subsequent retry occurs at 60 minute intervals.
• For example, if retries is 3, the system will try connecting again in 5 minutes if the initial connection attempt fails. If this retry attempt also fails, the system attempts a second retry in 10 minutes. The third retry attempt is made 15 minutes later. If the third retry attempt fails, the message is given a failed status. So after four attempts (the first attempt plus 3 retries), the message fails. You can search for and manually resubmit failed messages in Message Tracker.
• Retries do not occur precisely at these intervals because each connection attempt takes some seconds, which varies by computer. So retries actually occur after the connection attempt time plus the interval.
• This control applies only to retrying to send messages, not receiving. It applies only to retrying to send related to transport issues. It does not apply to successfully sent messages for which receipts have not been received as expected. Another control, re-sends, determines how many times the system will resend a message when a receipt is not received from the partner. For information about resends, see reliable messaging in the collaboration settings chapter.
• Connect timeout (seconds) – Time in seconds Activator waits for a connection to the delivery exchange before the attempt times out. Although the default value is 30 seconds, this may be longer than the interval allowed by your operating system (OS). For example, Windows XP by default allows a maximum timeout of 20 seconds. The actual connect timeout interval is the lesser of the OS timeout and the value set in Activator.
• Read timeout (seconds) – Time in seconds Activator waits to read data from the delivery exchange before terminating the connection.
• User commands – Enter user commands such as SITE to be sent to the server after login. Commands must be entered in the exact case and format expected by the server. For example, most FTP clients allow “mkdir test”, but most servers only accept “MKD test”. Consult RFC 959 for a list of standard FTP commands. You can use FTP commands that do not make use of the FTP data connection. Commands that make use of the FTP data connection are not supported. In addition, specific servers may support other commands. Refer to the server documentation for more information.
• If any command fails, the remaining commands are not executed, and production to the FTP server fails. To avoid possible failures, preface any command with an “at” sign (@) to indicate that errors from that command should be ignored, for example, “@MKD test”. Preface any command with an asterisk to cause the entire line to be treated as a comment, for example, “*Create test directory”.
• This field is available for the FTP transport only.
• Command set file key – The FTP command set file controls the commands sent to the FTP server for operations such as send, receive, delete. The default command set file is ftpcommandset.xml. This field lets you specify a different command set file. In most cases you can use the default value. Changing this is only for advanced FTP users with specialized needs.
• The field value is the name of an entry in filereg.xml in <install directory>\conf that points to another file in the conf directory. The following is the entry in filereg.xml for the default ftpcommandset.xml file:
• <File name="ftpcommandset.xml" path="conf/ftpcommandset.xml"/>
• If you want to add a new command set file, create the file and add an entry for it in filereg.xml. For example, if your new command set is called myftpcommandset.xml, enter that name in the field and add the following entry to filereg.xml:
• <File name="myftpcommandset.xml" path="conf/myftpcommandset.xml"/>
• Delete file after it is downloaded – Select this if you want the server to delete files after they have been downloaded from it. This option should be enabled in most cases. Most servers do not delete files after clients have downloaded them. However, some servers do. If an external server automatically deletes files that have been downloaded, deselect this option. This option applies only to delivery exchanges using external FTP servers for picking up messages from integration or receiving messages from partners.
• Enable file filtering – Available for some exchanges used for application pickups and for receiving from partners, file filtering allows Activator to discriminate which files to consume based on file names.
• In the file name filter pattern field, type the formats of the files you want the transport to consume or ignore. Use conventional wild card characters for file names or extensions or both. The following describes the supported characters and symbols:

• *	One or more characters.
  ?	Any single character.
  [ ]	Matches any single character within the brackets. For example, r[aou]t matches rat, rot and rut.
  ,	Commas can be used as and/or operators within brackets (for example, r[a,o,u]t).
  -	Use hyphens within brackets to specify ranges of letters or numbers. For example, [0-9] is for any number between 0 and 9, and [A-Za-z] is for any upper- or lower-case letter.
  .	Use the character dot to separate the file name and extension. For example, *.txt.
  |	Use the pipe character to separate multiple file-name formats. For example, *.edi|*.txt|[a,b,c]?.xml.

• Specify with the radio buttons whether the filter pattern is inclusive or exclusive. If inclusive, only files matching the pattern are consumed. If exclusive, files matching the pattern are ignored, but all other files are consumed.
• Activator ignores files that do not meet filtering conditions. Ignored files are not reported in Message Tracker. Such files also do not generate log messages unless the following property is set to debug in conf\log4j.properties:
• log4j.category.com.cyclonecommerce.tradingengine
• Back up the files that go through this transport – Indicates whether the system backs up copies of the messages it retrieves from integration or receives from partners.
• Backing up files is strongly recommended. This is required for the system to perform fail-over operations such as attempting to send messages again (retries) in case of a transport connection failure. Without backups, a message in process cannot be recovered if the server stops or restarts. Backups also are needed if you want the ability to resubmit messages to a back-end application or resend messages to partners.
• Backup files are stored in \<install directory>\common\data\backup, unless you specify otherwise.
• Post-processing script – The full path to an executable file that contains post-processing commands. This field is available for community integration delivery exchanges and partner trading delivery exchanges.