FTP (embedded) transport configuration

A community can use an embedded FTP server to receive messages from partners or applications.

When you elect to set up an embedded FTP transport for a community, the exchange wizard asks whether you want to:

  • Use a previously defined embedded FTP server (if available)
  • Define a new embedded FTP server

If you choose to use a previously-defined embedded FTP server, the wizard prompts for the user account name. You can choose an existing account or define a new one. If you choose an existing account, you must choose a sub-directory within that account’s home directory that is not assigned to any other exchange point.

If you choose to define a new embedded FTP server, the wizard prompts for a server name and port number. The wizard then asks for a user name and password for the new server. If the default selections already are in use, you must use another user name and password.

Note For a description of configuring an external FTP server, see FTP (external) transport configuration.

Related topics:

Types of embedded FTP servers

There are two types of embedded FTP servers:

  • Trading servers are used for receiving messages from partners. In the simplest case, a partner’s FTP client connects to your embedded server to PUT a message for your community to pick up. There also is a more complex configuration — hosted embedded FTP — where your community lets partners connect to your embedded server to GET messages.
  • Application servers are used for retrieving messages from, or delivering messages to, back-end systems.

The exchange wizard enforces the usage context for embedded FTP servers. For example, the wizard does not let you define a new embedded FTP trading server when the usage requires an application server.

To configure hosted partner accounts for embedded FTP servers, you must have a specific license permission. Your license.xml file must enable the permission: hostedPartnerFtpAccounts. Without this permission you can configure a partner to send messages via an external FTP server, but not an embedded server. This permission does not affect back-end application accounts; there is no restriction on adding hosted accounts from which a back-end system can pick up messages.

Related topics:

Embedded FTP user accounts

When you add an exchange that uses an embedded FTP server, you must specify an FTP user account. You can select an existing account (if one exists) or define a new one. Activator internally associates user accounts with home directories for sending (PUT) or retrieving (GET) messages. There are three types of accounts.

Account type

Usage

Community FTP accounts

Community exchanges, trading servers only

Partner FTP accounts

Community and partner exchanges, trading servers only

FTP accounts for back-end application exchanges

Community exchanges, application servers only

User names are shared by all trading servers. This enables a load balancer to send a request to any trading server. However, user names associated with application servers are not related to user names shared by trading servers. For example, the user name user1 on the trading side is completely different from user1 on the application side.

The following topics describe each account type.

Community FTP accounts

Community FTP accounts are associated only with community pickups for receiving messages from partners.

Partners can perform PUT operations to community accounts associated with trading pickups, but not GET operations. This is to prevent partners from accessing each others’ files.

Partners can drop packaged messages directly into the home directory of a community account. As a result, community FTP accounts can be referred to as shared accounts.

When a community profile is exported as a partner profile file to be imported by partners, the community FTP account is exported with the FTP pickup exchange.

To avoid file name collisions you can use the Message attributes tab on the embedded FTP pickup exchange maintenance page to specify sub-directories where partners can place files based on the sender routing ID. This also allows identifying the sender when binary files are dropped off. For example, the following sub-directory scheme could be used for two partners (p1 and p2) to drop off files for community c1:

Sub-directory

Purpose

p1/c1

p1 sends to c1

p2/c1

p2 sends to c1

If a partner-specific sub-directory scheme is used, the partner must manually specify the sub-directory after importing the community's profile. If there is only one community and it has only one routing ID, the second directory level is unnecessary.

Partner FTP accounts

Partner FTP accounts are used only for trading. The accounts typically are used for outbound trading via deliveries set up for partners. But the same accounts can be used for inbound trading via pickups set up in communities. In this case they can be used in lieu of, or in addition to, community accounts.

The user interface segregates the two purposes. When adding a partner embedded FTP delivery exchange, the wizard suggests the /mailbox sub-directory under the home directory. This is where Activator delivers messages for the partner to pick up. This can be thought of as a hosted partner delivery exchange, since the partner is picking up messages from your server. If the same partner account is added to an existing community pickup exchange, the system suggests the home directory (/). This ensures outbound and inbound messages are not confused.

For hosted partner delivery exchanges, you must inform the partner performing the GET operation of the FTP host name or IP address, the port number, the path, and the server user name and password. If your partner uses Axway products B2Bi, Interchange or Activator, the partner must add a community pickup exchange for receiving messages via an external FTP server (see FTP (external) transport configuration). The default value of the pickup directory must be changed to mailbox or whatever directory you specified. Also, clear the option for use temporary files.

Partner FTP accounts cannot be used by back-end application exchanges.

Outbound trading example

In this example, an administrator adds an outbound hosted FTP delivery exchange for partner1. The administrator associates the user account p1. The user interface suggests /mailbox as the sub-directory where the partner retrieves (GET) messages.

Optionally, for binary trading the use the Message attributes tab of the embedded FTP pickup maintenance page to specify sub-directories where Activator delivers files based on the routing ID of the sending community. For instance:

Sub-directory

Purpose

p1/mailbox/c1

p1 GETS messages from community1

p1/mailbox/c2

p1 GETS messages from community2

Since partner FTP accounts are partner-specific, message attribute mapping only is needed for identifying the community if there is more than one possible sending community or there is no other way to identify the community. This would be the case when you intend to trade binary files, which have no packaging or internal identifying information.

Message attribute mapping also can be used to sort messages into arbitrary sub-directories based on other metadata besides the sender or receiver. For example, an inline process could assign metadata items to outbound messages that would cause them to be sorted into sub-directories based on mappings specified on the Message attributes tab.

Inbound trading example

This example is for traders who do not want to upload files to a shared community FTP account.

An administrator adds or selects a community embedded FTP pickup exchange. The pickup exchange can be one already associated with a community FTP account, such as c1. The pickup exchange provides an anchor for one or more partner FTP accounts where files may be dropped off for the community.

The administrator selects the Directories tab on the community pickup exchange. There the administrator can add a new partner account or select an existing one.

The user interface suggests / as the home directory for the FTP account where partners can drop files for the community. In contrast, /mailbox is the suggested directory when a hosted delivery exchange is added for a partner to GET messages.

Note Embedded FTP servers treat paths beginning with a slash as starting at the home directory for the user account currently logged in.

FTP accounts for back-end application exchanges

Application FTP accounts are associated only with application pickups and deliveries for retrieving messages from, or delivering messages to, back-end systems. Application pickup exchanges are not tied to a particular community.

When you create an FTP account you can choose to either use an existing account, a new account (with all fields empty), or to define one later.

When defining an embedded FTP pickup for the first time, the exchange wizard suggests the generic name application as the FTP account name. The same user name is offered for the first FTP application delivery exchange. The difference is \out is suggested as the pickup subdirectory name and \in is suggested as the delivery subdirectory name. You can change the user names and subdirectories as long as the same combination of user name and subdirectory is not specified for two exchanges. This is true for all embedded FTP exchanges.

Related topics:

Firewalls, load balancers and embedded FTP

FTP servers present challenges with firewalls and load balancers. If you have a corporate firewall and the computer running Activator also has a Windows firewall, turn off the Windows firewall. Ask the network administrator to open the control port for your embedded FTP server (default is 4021) on the network firewall. You also may need to ask the administrator to open a range of ports for passive connections (see Advanced tab, Allowed passive ports field).

In the early days of the Internet it was common for an FTP client to use port mode. The data connection was established from the server back to the client, even though the original control connection was always established from the client to the server.

The client is generally less prepared than the server to open firewall ports, and passive mode has become the standard (Windows command line FTP client is an exception). In passive mode, when the client wants to perform a GET, PUT or LIST operation, the server creates a temporary socket listening on a port specifically for that client, usually at a high number like 50,000. The client then makes the data connection to the server, performs the transfer and the connection is dropped. The control connection remains active.

Most firewalls in use today allow the client through on the temporary data port, even if the port is not explicitly configured to be open. This is safe because the firewall can eavesdrop on the initial control connection from the client and notice it is an FTP connection. If the connection is non-SSL, the firewall also can notice the temporary port the server assigned for the client to establish the data connection. Subsequently when the client tries to connect again on that port, the firewall allows the connection on a one-time basis to the temporary port.

Load balancers present a similar problem. If the load balancer is FTP-aware, it can route incoming data connections to the same server as the associated control connection. But the load balancer cannot do this in the case of SSL. It must be configured to route all connections from the same origination IP address to the same server until there are no more connections from that IP to that server.

Related topics:

Embedded FTP fields

Configure server fields

When you add a new embedded FTP server to a community, you complete the following fields in the exchange wizard.

  • Server name – Enter a name for the new embedded FTP server. This can be any name you want. You can select this server when setting up additional embedded FTP delivery exchanges later.
  • If this is the first server, the wizard suggests the name Trading FTP if the server is to be used for receiving messages from partners or Application FTP if the server is to be used for exchanging messages with a back-end system.
  • Port – The port number that listens for incoming FTP connections. This is known as the control port. The wizard suggests a port not in use and displays a list of ports in use by Activator. You can use the suggested port or another.
  • If this is the first server, the wizard suggests — if not already in use — 4021 for a trading server or 5021 for an integration server. For security reasons, trading and integration servers must use different ports.

Select or create user account fields

You have the following options for selecting a user account:

  • Select an existing account from the drop-down list (if available)
  • Define a new account
  • Define an account later

If you elect to define a new account, complete the following fields. If you are defining the first user account, the wizard suggests for the user name and password the community default routing ID for a trading server or application for a back-end application server.

  • User name – The user name to connect to the server. Not only does your partner use this name to connect, but Activator creates a directory of the same name. This is the home directory for the FTP account. It is where a partner sends messages to your community via FTP. If you use the default location for the common directory, the directory is at <install directory>\common\data\ftp\users\trading. But if you are configuring an application transport, the path is <install directory>\common\data\ftp\users\integration.
Caution   Do not configure a back-end system to retrieve files from or write files to common\data\ftp\users\trading. Doing so could result in operational difficulties. The back-end system must always interact with trading engine application-type transports, and allow Activator to route messages to and from trading-type transports.
  • Password – The password to connect to the server.
  • Confirm password – The password to connect to the server. Anonymous connections are not supported.
  • Transport user password policy – Select the password policy to assign to the user. See Manage password policies of transport users for more information.

Click Next to continue the configuration.

Select a destination directory

  • Enter a new path – This field enables you to associate the same embedded server and user account to multiple sub-directories. Each sub-directory can be used by a single partner to send messages to your community via FTP.
  • If you leave this field blank, the effective directory where a partner uploads messages is the top-level directory. For example:
  • common\data\ftp\users\trading\<user account>
  • But if you add an amended path, the effective directory is the specified sub-directory. For example:
  • common\data\ftp\users\trading\<user account>\< amended path >
  • For the first integration server, the wizard suggests an amended path of in for integration delivery or out for integration pickup. By default the home directory (/) is not used, but you can change this.
  • Activator keeps track of the embedded FTP directory structure for you. Do not manually change any directories Activator creates for managing messages transported via embedded FTP servers.

Click Next if you want to name the exchange. Otherwise, click Finish.

Related topics:

Related Links