Modify a Web Services API client application pickup or delivery

This topic describes the fields on the maintenance pages for Web Services API client pickups and deliveries.

The maintenance pages display the transport fields that can be changed, while the delivery wizard has only the most commonly used. The following are the fields on the settings and advanced tabs.

Web Services API client settings tab

URL

The URL Activator uses to post messages to a back-end system.

Advanced tab (Web Services API client)

Maximum concurrent connections

The maximum number of concurrent connection Activator can open to the remote server.

For example, if the value is 100 connections and there are 150 messages to send, Activator opens only 100 connections to that partner. The remaining 50 messages are queued until connections become available. The default value is suitable in almost all cases. However, if a partner reports that your Activator configuration is overrunning the receiving system, decrease the value.

Retries

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 includes the receipt if synchronous receipts were requested. Otherwise, it is 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 tries 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 4 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, resends, determines how many times the system resends a message when a receipt is not received from the partner. For information about resends, see Default collaboration fields in the collaboration settings chapter.

Send the entire payload contents

Send the payload through this transport. This option is only for integration delivery.

Send the payload URL only

After the transport has been set up, you have the option of sending the message payload (the default) or only the URL that points to the payload. If you choose to send only the URL, the back-end system uses the URL to retrieve the payload from the Activator backup directory. Because the payload is retrieved from the backup directory, there are two conditions that must be met if you choose to send the payload URL only:

  • Backing up files must be enabled for the Web Services API client integration delivery exchange.
  • If you have set up a schedule on Activator for deleting messages, the back-end must retrieve the payload before the next scheduled purge occurs or the payload is lost. For information about setting up schedules for deleting messages see Data storage, backups, and purging.

Response timeout (seconds)

Time long in seconds Activator waits for the delivery exchange to respond to a request before terminating the connection.

Enable HTTP chunking

If you are sending files larger than 2 gigabytes, select this to turn on chunking. A chunked message is a large message broken into smaller pieces for sending to a partner over the Internet or to back-end integration.

Although primarily for handling large messages, chunking can be enabled for small messages, too. However, if your partners use a trading engine other than Activator or use an external or staged HTTP server, they may be unable to accept messages larger than 2 gigabytes, even if the messages are chunked.

Also, in rare cases a partner’s HTTP server may be unable to handle chunked messages, regardless of message size. You should perform tests to determine whether a partner’s server can handle chunked messages. If not, the partner must use Activator with the embedded server to receive large chunked messages successfully.

If you enable chunking because of large messages, you also probably need to request that receipts be sent over an asynchronous connection. See the chapter on collaboration settings for details.

Attempt restarts

Select this option to turn on checkpoint-restarts. A checkpoint is information saved to disk that is used as a recovery point in the event of a transport failure. The restart program uses the last saved checkpoint and starts again, ensuring no loss of data.

Checkpoint files are saved on the server under the < install directory>/common/data/http/restartable.

To reduce unnecessary overhead when processing small files, checkpoint files are only created for messages that are at least 100 KB in size.

If a restart is attempted for a message whose checkpoint file on the server is more than four hours old, the checkpoint file is discarded and the entire message is retransmitted.

The restart logic is used only during transport retries, such as might occur when a transfer is interrupted due to network problems. If you resubmit a message in Message Tracker, no attempt is made to perform a checkpoint-restart.

This feature only works if your partner uses B2Bi, Interchange or Activator and its embedded HTTP server. Do not select this option if a partner uses an external or staged HTTP server or uses a trading engine other than B2Bi, Interchange or Activator.

Enable use of 102-processing

Select this option to ensure that the connection between the client and server does not become idle and fail while message processing is in progress. For example, this makes sure the connection remains active when the client is sending a multi-gigabyte message. Or, to prevent a firewall from disconnecting an idle connection before the server receives the entire message and returns a 200 OK response. Most often this setting is useful when the client requests a synchronous receipt, but also could be recommended in some cases for an asynchronous receipt.

Selecting this option directs Activator to add the following to the header of an outbound message: Expect: 102- processing. This is an HTTP response code that indicates processing is in progress. If the receiving server supports 102 responses, the header triggers the server to send 102 responses to the client repeatedly until the server has completely processed the inbound message. Before selecting this option, make sure the server supports 102 responses. If you turn on 102 processing and the server does not support it, the server will return a 417 message (the server could not meet the expectation given in the Expect header) and the connection may fail. If the receiving partner uses the embedded HTTP server in Interchange or Activator 5.5.1 or later, 102 responses are supported. This also is supported if your partner uses Jetty 6 or later.

Back up the files that go through this transport

Select this option if you want the system to back up copies of the messages it consumes. 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.

Post-processing script

The full path to an executable file that contains post-processing commands.

Web Services API server settings tab

Embedded Web Services API server

Click the link to display the settings for the global Web Services API server.

Advanced tab (Web Services API server)

Back up the files that go through this transport

Indicates whether the system backs up copies of the messages it consumes. Backing up files. 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 are needed 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 the back end or receiving messages from partners

Related topics

Related Links