SMAFT File Transfer job

Behavior-level reference for building and diagnosing SMAFT File Transfer jobs.

Task walkthrough: Transfer a file between two LSAM machines. This page is the full configuration and troubleshooting reference.

The SMAFT File Transfer job moves a file from one legacy LSAM machine to another using SMA's file-transfer protocol. It is the only job type that names two machines, and the only one whose machine is derived from its own parameters instead of being picked in Agent Assignment.

Property	Value
Job type	SMAFT File Transfer (smaft-file-transfer)
Plugin	SMAFT File Transfer (lsam-smaft)
Category	File Transfer
Runs on	Legacy LSAM agents — Windows and UNIX
Connections	Up to two batch users, one per end — Windows or UNIX, matching each machine's platform
Relay	Required, like every legacy job type

Both machines must carry a file-transfer endpoint before a transfer can be built — see Before you can build one.

The two machines, and which one runs the job

You name a Source Machine (which holds the file) and a Destination Machine (which receives it). Start Transfer On then decides which of the two runs the job:

Start Transfer On	Direction	The job runs on	Needs
Destination (the default)	Pull — the destination connects to the source and pulls the file	the destination machine	the source's file-transfer server reachable from the destination
Source	Push — the source connects to the destination and pushes the file	the source machine	full file-transfer support on both machines

The other machine — the one that does not run the job — acts as the file-transfer server for that transfer. This page calls it the peer.

The job editor shows the result as a read-only line, so you can see where the job will run:

Runs on: PAYROLL-WIN (pull — the destination connects to the source and pulls the file)

Agent Assignment is read-only on this job type

Because the machine follows from the parameters, Agent Assignment renders read-only and offers no agent pool and no legacy agent group. Change Start Transfer On or either machine and the assignment follows automatically. A transfer is always assigned to one specific machine.

Once derived, the job behaves like any other specific-agent job: it waits on that machine's availability in the ordinary way, and a long hold there is reported as a long hold. What is different is the peer — see The peer machine holds the job.

Before you can build one

Every machine that takes part in a transfer needs a file-transfer endpoint, configured per agent by an administrator. It is separate from the LSAM host the relay uses, because the two are reached over different network paths: the relay reaches the agent, while for a transfer the peer agent reaches it directly. See File-transfer endpoint for the fields and their defaults.

Two parts of that endpoint gate this job type:

• FT Role decides which pickers a machine appears in. Source only offers it as a source, Destination only as a destination, Both source and destination as either, and None in neither. The default is None — file transfer is opt-in, so a machine takes no part in a transfer until an administrator gives it a role, and no role was backfilled onto agents registered earlier.
• Full file-transfer support is what a push requires, on both machines. It defaults to enabled.

A Universal Agent has no file-transfer endpoint and can never take part in a transfer.

Configuration reference

Parameter	Type	Required	Default	Notes
sourceMachine	string	Yes	—	1–24 chars. Offered only if its FT role is source or both.
sourceFile	string	Yes	—	1–4000 chars, no ". Full path and file name. Wildcards * and ? are allowed — see Wildcard transfers.
sourceUserConnectionId	connection	No	unset	Batch user on the source machine. Its connection type must match that machine's platform.
sourceDataType	enum	Yes	Text	Text, ASCII, or Binary.
destinationMachine	string	Yes	—	1–24 chars. Offered only if its FT role is destination or both.
destinationFile	string	Yes	—	1–4000 chars, no ". Full path and file name to write.
destinationUserConnectionId	connection	No	unset	Batch user on the destination machine, matching that machine's platform.
destinationDataType	enum	Yes	Text	Text, ASCII, or Binary.
startTransferOn	enum	Yes	Destination	Source or Destination. Decides which machine runs the job.
ifFileExistsOverwrite	enum	Yes	Do not Overwrite	Do not Overwrite, Overwrite, Backup then Overwrite, Append, or Backup then Append.
deleteSourceFile	enum	Yes	No	No, Required, or Preferred. Anything but No needs both machines to be Windows.
maximumTransferRate	enum	Yes	>2048	Bandwidth cap in kbit/s: 64, 128, 256, 512, 1024, 2048, or >2048. It is a list of fixed steps, not a number — >2048 means uncapped.
compression	enum	Yes	None	Required, Preferred, or None.
encryption	enum	Yes	None	Required, Preferred, or None.
failIfPreferredSettingsNotSatisfied	boolean	Yes	false	Fail the job when a Preferred compression, encryption, or TLS setting could not be honored.
tlsSecurityOverride	enum	Yes	Preferred	Required, Preferred, or None. See TLS and the port.

Required and Preferred

compression, encryption, deleteSourceFile and tlsSecurityOverride share a three-way shape:

• Required — the transfer must have it, and fails if the two ends cannot agree on it.
• Preferred — use it if both ends can, otherwise carry on without it. Whether that silent downgrade fails the job is what Fail If Preferred Settings Not Satisfied decides.
• None — do not use it.

Data type

Text and ASCII translate line endings for the receiving platform; Binary does not. So a text transfer between platforms can legitimately arrive with a different byte count than it left with — LF becomes CRLF going to Windows, and CRLF becomes LF going to UNIX. Use Binary when the file has to arrive byte-for-byte identical.

Binary must be set on both ends. One end streaming raw bytes while the other translates text corrupts the file silently, so a mismatch is refused when you save.

Text works wherever the job runs. Earlier builds rejected it on a transfer whose job ran on a UNIX machine — the transfer failed on an Unsupported Data Type from that end, with Text being the default on both ends — so in practice only a Windows-run transfer accepted it. Nothing about the job needs changing.

The batch user on each end

A transfer authenticates on both machines, so each end takes its own batch user — picked from your saved connections, filtered to the platform of the machine that end names.

Machine platform	Blank Batch User
Windows	Allowed. The transfer runs as the agent's own service account.
UNIX	Not allowed. The job fails at dispatch — UNIX has no service-account equivalent, so a real user and group are needed.

A UNIX batch user needs both a user and a group, and neither may contain / — the agent splits the pair on the first slash it finds. See Batch User.

TLS and the port

The port a transfer dials belongs to the peer — it is the machine being connected to — but the TLS switches are checked on both ends, because a TLS handshake needs both halves to speak it.

TLS Security	Behavior
Required	Use TLS. If either machine does not support TLS, or the peer has no TLS port, the job fails.
Preferred (the default)	Try TLS; if the pair cannot do it, fall back to the non-TLS port.
None	Use the non-TLS port. Fails if either machine does not support non-TLS.

If no port can be resolved for the mode you asked for, the job fails naming the machine and the mode, rather than dispatching a transfer that cannot connect.

Only non-TLS transfers are verified end to end in this release

TLS is fully modeled — the switches, the port pair, and the fallback all behave as described — but it has not been proven on the wire. Non-TLS transfers have been, in both directions, on real Windows and UNIX agents. Treat TLS Security = Required as unverified for now.

Rules

The rules live at three points, and which point catches a mistake decides what you see.

Refused when you save

These need nothing but the job's own parameters, so the editor refuses the save and names the field:

• Both machines are required.
• Start Transfer On must be Source or Destination.
• The source and destination must not be the same file on the same machine — there would be nothing to transfer. The same machine with different paths is fine; that is a local copy.
• A Binary data type must be set on both ends.
• The job must be assigned to the machine that runs the transfer. Normally the editor keeps this true for you; a configuration written around the editor — a Code tab edit, an import, or a direct API call — can break it, and this is what catches that.

Fails at dispatch

These need the agent records, so they are checked when the job is dispatched. Each one terminates the job, and the reason is recorded as the job's termination description:

• Either machine is not registered.
• Either machine has no file-transfer configuration — a Universal Agent, for instance.
• The source machine's FT role cannot act as a source, or the destination's cannot act as a destination. The message names the machine, names its role in words rather than as a protocol code, and states the role to set — … has file-transfer role 'none' and cannot act as a transfer source. Set its FT Role to 'source' or 'both' on the agent. Because none is the default, this is the most likely reason a first transfer fails on a newly configured platform.
• Start Transfer On = Source and one or both machines lack full file-transfer support. Both offending machines are named at once, so one pass fixes it.
• The peer machine has no file-transfer address.
• No port could be resolved for the TLS mode you asked for.
• A UNIX end has no batch user, or a batch user's type does not match its machine's platform.

Checked as the transfer is built

The last group is applied when the job is handed to the agent, and each one fails the job naming the field:

• Binary symmetry, again — a config that reached this point around the editor is still refused.
• Delete Source File other than No requires both machines to be Windows. The UNIX agent hard-fails a delete request.
• The wildcard restrictions below.

Wildcard transfers

* and ? in either file name transfer more than one file. When a wildcard transfer involves a UNIX machine at either end, three settings are constrained:

Setting	Must be
If File Exists	Overwrite
Compression	None
Encryption	None

Each is reported separately, naming the field, so you are not sent round the loop fixing one at a time. A wildcard transfer between two Windows machines has none of these restrictions.

The peer machine holds the job

The machine that runs the transfer is gated on availability like any other assigned agent. The peer is gated too — and differently:

• If the peer is offline, marked offline or draining, or its status cannot be determined because its relay feed has gone stale, the job holds. It is re-evaluated on every scheduling pass and clears by itself when the peer comes back. Nothing terminates and nothing is rerouted.
• Force-start does not bypass this hold. That is deliberate, and it is the one place a transfer differs from every other legacy job: forcing a job whose peer file-transfer server is down cannot succeed, because there is no server to connect to, so bypassing would turn a hold into a certain failure.

Outcomes

The agent's verdict is recorded as it stands. Unlike most legacy job types, a SMAFT job has no exit-criteria setting and none is applied for you — whatever the file-transfer agent reports is the job's outcome.

Verify the file, not just the job

Because the agent's verdict is trusted verbatim, check that the destination file is what you expect rather than reading success alone — particularly on a wildcard transfer, where a partial match still completes.

Troubleshooting

Symptom	Likely cause
A machine is missing from the Source Machine or Destination Machine list	Its FT Role excludes that direction, or it is a Universal Agent. A role of None is the default, so a machine nobody has configured is absent from both lists. Roles are per agent — see File-transfer endpoint.
The job fails at dispatch saying a machine's file-transfer role cannot act as a source or destination	That machine has no FT Role set, or one that excludes the direction. The message names the role to set. A saved job is not re-checked against the role until it is dispatched, so a job built before the role was set fails here rather than at save.
The save is refused naming a field you can see is filled in	Read the message: the two most common are the same-file-on-the-same-machine rule and Binary set on only one end.
The job holds indefinitely and nothing is logged as failed	The peer machine is unavailable. It clears when the peer returns; force-start will not move it.
Job failed with no further detail, and the source file is missing	A missing source file fails the job with the agent's own return code, but the agent's explanatory text is not surfaced into the termination description in this build. Check the file exists and is readable by the batch user for that end.
A transfer fails with Unsupported Data Type and Transfer failed!	A data type of Text on a transfer whose job ran on a UNIX machine. Fixed — Text is accepted at both ends whichever platform runs the job. If you see it, the platform needs upgrading; changing the job's data type is not the fix.
A transfer arrives with a different byte count than the source	Expected on a Text or ASCII transfer between platforms — line endings were translated. Use Binary for a byte-for-byte copy.
A push fails naming both machines	Start Transfer On = Source needs full file-transfer support on both. Either enable it on both, or switch to Destination and pull instead.
The transfer connects but the credentials are rejected on one end	Each end authenticates separately. Check the batch user attached to that end, and that its type matches that machine's platform.
TLS Security = Required fails to resolve a port	One machine does not support TLS, or the peer has no TLS port set. Note that TLS is not verified end to end in this release.

Contact support when

• A transfer completes successfully but the destination file is wrong or truncated.
• A peer machine reports as available everywhere else but a transfer still holds on it.
• A machine has an FT role and address configured and still reports as having no file-transfer configuration.