Managed calls

Managed File Transfer (MFT) agents are typically used to transfer files or messages. These are known as Managed Transfers. Agents can also be used to run commands, scripts or JCL without the need for transferring files or messages. This capability is known as Managed Calls.

Managed call requests can be submitted to an agent in several ways:

Using the fte:call Ant task.
Configuring a resource monitor with a task XML that runs a command or a script. See Configuring monitor tasks to start commands and scripts for more information.
Directly putting an XML message into the agent's command queue. See File transfer request message format for more details on the Managed Call XML schema.

For managed calls, the directory containing the command or script that is being run must be specified in the agent property commandPath.

Managed calls cannot run commands or scripts that are located in directories which are not specified in the agent's commandPath. This is to ensure that the agent does not run any malicious code.

Important: To ensure this is the case, by default, when you specify commandPath:

Any existing agent sandbox is configured by the agent when it starts up so that all commandPath directories are automatically added to the list of directories that have denied access for a transfer.
Any existing user sandboxes are updated when the agent starts up so that all the commandPath directories (and their sub-directories) are added as <exclude> elements to the <read> and <write> elements.
If the agent is not configured to use either an agent sandbox, or user sandboxes, then a new agent sandbox is created when the agent starts up that has the commandPath directories specified as denied directories.

Additionally, you can also enable authority checking on an agent to ensure that only authorized users are allowed to submit managed call requests. For more information on this, see Restricting user authorities on MFT agent actions.

The command, script, or JCL invoked as part of a managed call runs as an external process, which is monitored by the agent. When the process exits, the managed call completes and the return code from the process is made available to either the agent or the Ant script that invoked the fte:call Ant task.

If the managed call was started by the fte:call Ant task, then your Ant script can check the value of the return code to determine whether the managed call was successful or not.

For all other types of managed calls, you can specify which return code values should be used to indicate that the managed call completed successfully. The agent compares the return code from the process against these return codes when the external process finishes.

Note: Because managed calls run as external processes, they cannot be canceled once they have started.

Managed calls and source transfer slots

An agent contains a number of source transfer slots, as specified by the agent property maxSourceTransfers, described in Advanced agent properties: Transfer limit.

Whenever a managed call or a managed transfer is run, they occupy a source transfer slot. The slot is released when the managed call or managed transfer completes.

If all the source transfer slots are in use when an agent receives either a new managed call or managed transfer request, the request is queued by the agent until a slot becomes available.

If a managed call starts a managed transfer (for example, if a managed call runs an Ant script and that Ant script uses the fte:filecopy or fte:filemove task to transfer a file), then two source transfer slots are required:

One for the managed transfer
One for the managed call

In this situation, it is important to note that if the managed transfer either takes a long time to complete, or goes into recovery, then the two source transfer slots are occupied until either the managed transfer completes, is canceled or times out due to a transferRecoveryTimeout. See Transfer recovery timeout concepts for details on transferRecoveryTimeout. This can potentially limit the number of other managed transfers or managed calls that the agent can process.

Because of this, you should consider the design of a managed call to ensure that it does not occupy source transfer slots for a long period of time.

Using the REST API with managed calls

The HTTP GET and HTTP POST verbs are supported for enabling managed calls, and work only on Version 3 of the REST API.

Other verbs, for example, HTTP DELETE and HTTP UPDATE are not supported and return the HTTP 405 error code if you attempt to use them.

Attention: Once submitted a managed call cannot be canceled using the REST API.