Run commands on legacy LSAM machines

If you already run legacy LSAM agents, OpCon Continuum can drive them directly. You don't need to rebuild that automation to start orchestrating it. The UNIX Command and Windows Command job types run a program on an existing UNIX/Linux or Windows LSAM machine through the relay, Windows - WS_FTP Pro runs a WS_FTP Pro file transfer on a Windows LSAM machine, four Windows - Command: File … job types copy, move, rename, or delete files without you writing a command line, Windows - Corelation submits and monitors a Corelation batch job, two Windows - Fiserv DNA job types run a Fiserv DNA SQT job or a file load, Windows - File Arrival and UNIX - File Arrival wait for a file to turn up on the machine, MS SQL Script runs T-SQL on a SQL LSAM machine, and SMAFT File Transfer moves a file between any two of these machines, Windows or UNIX.

What this solves

You're adopting OpCon Continuum but still have working automation on legacy LSAM machines. Rebuilding all of it before you can orchestrate anything would stall the whole move.

Use it when

• You're moving to OpCon Continuum but still have automation on legacy LSAM machines.
• A workflow needs to run a program on a UNIX/Linux or Windows LSAM machine.

Add an LSAM command to a workflow

To add an LSAM command, complete the following steps:

1. Go to Workflows and open the workflow you want to edit.
2. Add a job: on an empty workflow select First Job, otherwise select New Job from the Job Tools panel.
3. In the job editor, select the Job Definition tab.
4. Select Show Job Types.
5. In the job type catalog, under Integration, select UNIX Command or Windows Command.
6. Under Job Parameters, set the machine and the program to run (see below).
7. Select Save & Close.

Settings

Setting	Notes
Machine name	The LSAM machine to run on. It must match the machine name registered with the relay.
Program / start image	The program or script to run on the machine.
Arguments	Command-line arguments for the program.
Working directory	Where the command runs on the machine.
Prerun command	An optional command run before the main one.
Batch user	The account the job runs as — a saved connection of the platform's batch-user type, picked from a list. On UNIX it is required. On Windows and SQL leaving it blank runs the job as the agent's own service account; on IBM i, under the job description's default user. See Batch users.
Environment variables	Extra environment variables (Name = Value) for the job. Supported on both Windows and UNIX LSAM.
Exit criteria	Conditions tested against the job's exit code — up to 20 of them, plus an Exit Criteria Result that says whether a match means Fail or Finish OK. Leave it empty to fail on any non-zero exit code. See Set exit criteria.

Quotes in a UNIX command arrive as you typed them

A UNIX job's program, arguments, prerun command and environment values are sent to the machine unaltered, so /bin/sh -c "exit 3" runs what you wrote. Earlier builds converted ", &, <, > and ' into their XML forms on the way, and a UNIX agent doesn't convert them back — the shell was handed the converted text, and a command with a double quote in it ended with exit 127 and quot: not found in the log. If you worked around that by avoiding quotes, you no longer need to.

Two character sequences can't be carried in a UNIX value and are refused at dispatch: </F> and <F I=. The agent would read either as part of the message rather than as your text. Neither has a use in a shell command; if you need those characters, put them in a script on the machine and run that.

Windows LSAM commands also support:

• Run in command shell: run the command inside a command shell instead of starting the program directly.
• Output parsing: scan the job's output for text (Contains / Does Not Contain) and set an exit code when it matches, so a job that "succeeds" but logs an error can still be flagged failed. Up to five rules.
• Custom log file: the log file that output parsing scans; defaults to the job's standard output.

UNIX commands also support group, process priority, and signal/core-dump failure conditions.

Set exit criteria

Leave exit criteria empty and the job fails on any non-zero exit code. Set them and you decide what the code means. The setting is offered on UNIX - Command, Windows - Command, Windows - Embedded Script, Windows - Web Services and SQL - MS SQL Script, and on no other legacy job type.

There are two parts to get right, and the second is the one people miss:

1. The rows. Up to 20, each an operator and a Value. The operators are Equal To, Not Equal To, Less Than, Greater Than, Less Than or Equal To and Greater Than or Equal To, plus Range, which also takes an End Value and includes both ends. The rows are an OR — the code matches the table if it matches any row. End Value only appears on a Range row, so if you cannot see the field, check the operator.
2. Exit Criteria Result. One setting for the whole table: does a match mean Fail (the default) or Finish OK? And whichever you pick, a code that matches nothing gets the opposite. There is no "no rule matched" middle.

So the same intent can be written two ways, and you should pick whichever is shorter to read:

You want	Rows	Exit Criteria Result
Fail on 5 and on anything above 100	Equal To 5, Greater Than 100	Fail
Finish OK on 0, 3, and 10–20 — fail on everything else	Equal To 0, Equal To 3, Range 10–20	Finish OK

Two rules the editor enforces as you go: a range row must carry an End Value, and that End Value must be greater than or equal to its Value. Either mistake would make the row impossible to match — and because unmatched codes take the opposite outcome, it would quietly give the job the wrong verdict. The workflow refuses to commit and names the row: Range criterion #2 needs an End Value.

Good to know

Write the criteria against the code the agent actually reports, which you can read as the job's Return Code on the Processes page. On UNIX in particular, a code of 128 or above arrives as a negative number unless the agent has been configured otherwise.

caution

Finish OK, ranges, and rows past the fifth need a current relay

Those three forms are enforced by OpCon Continuum after the agent reports, rather than by the agent itself, and they depend on relay changes. A relay on an older build refuses the dispatch rather than sending a table it cannot represent, so the job will not start until the relay is upgraded. Ask your Administrator before building a workflow around them. Up to five plain conditions with the default Fail work on any relay build.

When OpCon Continuum decides the outcome, it records Finished OK (Exit Criteria) Return Code='3' in the job's history, which is worth knowing because the agent's own log was given the default and will say the opposite. The job's termination text keeps the exit code on these job types, so an Exit Description event written for a particular code still fires.

Pick the account the job runs as

Every legacy job type has a Batch User field. Rather than typing a user name into the job, you pick a saved connection that holds the account — the Administrator defines it once and you reference it. Nothing sensitive lands in the workflow.

The picker offers only connections of your job's platform type, and you can search it by name. What a blank field means depends on the platform:

Platform	Connection type	Blank means
Windows	Windows Batch User	The job runs as the agent's own service account.
UNIX/Linux	UNIX Batch User	Not allowed — a UNIX job must name one.
IBM i	IBM i Batch User	The job runs under the job description's default user.
SQL	SQL Batch User	The job runs as the agent's own service account, with no impersonation.

These fields replaced the typed-in run-as values

A Windows job used to accept only the literal Use Service Account, and UNIX and IBM i jobs carried a user and group you typed in. Those fields are gone. If you are opening a UNIX or IBM i job you built before the change, re-pick the account from the Batch User field — the old typed-in value is no longer read, and a UNIX job without a batch user fails when it runs.

If the account you need isn't in the list, ask your Administrator to define it — see Manage connections.

Transfer files with WS_FTP Pro

On a Windows LSAM machine that runs Ipswitch WS_FTP Pro, the Windows - WS_FTP Pro job type runs a file transfer using WS_FTP Pro's own site profiles. You pick the job type the same way as a Windows Command (Show Job Types → Integration → Windows - WS_FTP Pro), then fill in the transfer.

Before you start: the source and destination site profiles must already be set up in WS_FTP Pro on that machine. The job refers to them by name and stores no passwords or connection details; WS_FTP Pro supplies those from the profile.

Setting	Notes
Machine name	The Windows LSAM machine to run on (must match the name registered with the relay).
Batch user	The Windows Batch User connection the job runs as. Leave it blank to run as the agent's own service account.
WS_FTP Pro location	The folder containing wsftppro.exe on the machine.
Source profile / Source file	The WS_FTP Pro site profile name for the source, and the file to transfer.
Destination profile / Destination file	The site profile name for the destination, and the file to write.
File transfer options	Optional extra WS_FTP Pro command-line switches (for example, -binary -delete).

All fields except the options are required. Profile names can't contain a colon (:), and none of the text fields can contain a double quote ("). The form won't stop you from saving an invalid value: an empty required field, a stray " or :, or a location that's too long fails when the job is dispatched, not while you're editing, so double-check these before you run it.

Copy, move, rename, or delete files

For routine file housekeeping on a Windows LSAM machine you don't have to write an xcopy or del command line by hand. Four Windows - Command: File … job types build it for you. Pick one the same way as a Windows Command (Show Job Types → Integration), then fill in the files:

Job type	What it does	Key settings
File Copy	Copies files using xcopy	Source, destination, destination type (file or directory), and toggles for verify, short names, and subdirectories.
File Move	Moves files, overwriting the destination	Source, destination.
File Rename	Renames a single file (won't overwrite an existing name)	Path and current file name, new file name.
File Delete	Deletes files or directories using del	The file(s) to delete — a comma-separated list, wildcards allowed — plus optional force-delete-read-only, include-subdirectories, and per-attribute filters.

All four run as whichever Windows Batch User connection you attach, or as the agent's own service account when you leave the field blank, and File Copy and File Delete each have an optional Other options field for extra command switches. A path can contain spaces or unusual characters — the relay quotes it for you.

File Delete can also filter by file attribute — Read Only, Not Content Indexed, Archive, Hidden, System, and Reparse Point. Set a filter to Include to delete only files carrying that attribute, or Exclude to skip them; leave it unset to ignore the attribute.

As with WS_FTP Pro, these fields are checked when the job runs, not while you're editing. An empty required field, an invalid attribute filter, or a command line that's too long fails at dispatch, so double-check the paths before you run it. Options that would pause for a prompt (such as del /P) are ignored, so an unattended job can't hang waiting for an answer.

Submit a Corelation batch job

On a Windows LSAM machine that has SMA's Corelation connector installed, the Windows - Corelation job type submits a Corelation batch job and waits for it to finish. Pick it the same way as a Windows Command — Show Job Types → Integration → Windows - Corelation — then fill in the job.

Before you start: the Corelation connector (SMARunCorelationJob.exe) and a configuration file holding the Corelation connection details must already be in place in the connector folder on that machine. The job runs as whichever Windows Batch User connection you attach, or as the agent's own service account when you leave the field blank.

Setting	Notes
Machine name	The Windows LSAM machine to run on (must match the name registered with the relay).
Batch user	The Windows Batch User connection the job runs as. Leave it blank to run as the agent's own service account.
Connector location	The folder containing SMARunCorelationJob.exe. It's also the job's working directory.
Corelation job	The job to submit — its name, or its serial if you set Type to Job Serial.
Configuration file	The connector configuration file holding the connection details. Defaults to .\SMARunCorelationJob.ini.
Batch server / Batch queue	Optional. Leave the queue blank to use leastbusy, which picks the least-loaded open queue.
Parameter format	Whether runtime parameters are passed as Batch Options (the default) or Parameters.
Parameters	Runtime Name/Value pairs, up to 99. Neither part may contain a double quote or a pipe.
Output options	Log the request/response XML (on by default), the submit response, the job list, or verbose debug output.

Setting Retrieve job details only means the Corelation job is not run — use it to inspect a job rather than submit it.

Run a Fiserv DNA job

On a Windows LSAM machine that has SMA's DNA connector installed, two job types run a Fiserv DNA job and wait for it to finish. Pick one the same way as a Windows Command — Show Job Types → Integration:

• Windows - Fiserv DNA runs a DNA SQT job: a DNA application (APPL), optionally scoped by cycle codes.
• Windows - Fiserv DNA (File Loader) loads a file into DNA. It always runs the PS_FILELOADER application, so instead of cycle codes you give it the file's name and its control totals.

Before you start: the DNA connector (SMARunDNAJob.exe) and its configuration file must already be in place in the connector folder on that machine, and the DNA/SQT (Oracle) credentials must be set in the configuration file's [SQRT Parameters] section. The job runs under the LSAM service account and carries no credentials of its own — the connector reads them from that file.

Setting	Notes
Machine name	The Windows LSAM machine to run on (must match the name registered with the relay).
Batch user	The Windows Batch User connection the job runs as. Leave it blank to run as the agent's own service account.
Connector location	The folder containing SMARunDNAJob.exe; it's also the job's working directory.
Configuration file	The connector configuration file (holds the DNA/SQT credentials). Defaults to .\SMARunDNAJob.ini.
Application name / number	The DNA application (APPL) to run. On the File Loader this is fixed to PS_FILELOADER. The number, if given, is used in preference to the name.
Effective date / offset	Optional run date and a day offset; leave the date blank to let the connector derive it from DNA.
Cycle codes	SQT job only — the cycle codes to run (for example EOM), or turn on cycle code not required to skip the connector's check.
File details	File Loader only — file name, batch count, record count, credits, debits, and file number. Each can be a literal value or the name of an OpCon property.
Parameters	Optional runtime parameters as Name/Value pairs (up to 99), each with optional date handling — a Business date or Calendar date, a day offset, and (for a calendar date) a date format.

All the text fields reject a double quote ("), and a cycle code or a parameter can't contain a " or a pipe (|). Runtime-parameter date handling has to be consistent — set a date type before an offset or a date format, and use a date format only with Calendar date. As with the other LSAM types, the form won't stop you from saving an invalid value — a blank required field, a stray " or |, inconsistent date handling, more than 99 parameters or cycle codes, or a value that's too long fails when the job is dispatched, not while you edit.

Wait for a file to arrive

Two job types do this — Windows - File Arrival on a Windows LSAM machine and UNIX - File Arrival on a UNIX/Linux one. Each waits for a file to appear and succeeds once a matching file has arrived and stopped changing, so you can put one ahead of the job that processes the file and know the file is really there before it runs. Pick either the same way as a Command job, under Show Job Types → Integration.

Unlike the other LSAM job types, File Arrival needs no connector and no command line — the LSAM agent watches for the file itself. You only describe what to watch for and when.

On a Windows LSAM machine

Setting	Notes
Machine name	The Windows LSAM machine to watch on; must match the name registered with the relay.
Batch user	The Windows Batch User connection the job runs as. Leave it blank to run as the agent's own service account.
File name	Full path and file name to watch for. Wildcards * and ? are allowed in the file-name part; the folder must already exist. UNC paths and %ENVVAR% references are fine; double quotes aren't.
Start / end offset	The watch window, each set as a Day Offset (whole days from the job's schedule date, -99 to 99) plus a 24-hour Time — so 08:00 on the schedule date is Day Offset 0, Time 08:00. The end can't be earlier than the start; to watch past midnight, move the end to the next day rather than back to an earlier time. Leave both at zero to check whether the file exists right now. This counts from the date the relay sends, so an out-of-date relay can shift the whole window by a day — see below.
File size stable time	Seconds to wait before re-checking the file, to confirm it's fully written: the size and timestamps must be unchanged across the interval. Defaults to 5.
Include subdirectories	Also watch subfolders of the given path. Off by default.

Day Offset is days, not minutes

The offsets used to be a single box taking the whole window in minutes, so 480 meant 08:00. Typing 480 into Day Offset now asks for a window 480 days out. The box refuses any day outside -99 to 99 and snaps back to the stored day when you leave it, so a rejected entry never looks accepted.

The window counts from the date the relay sends — check the relay build

Day Offset 0 is the job's schedule date, and the agent gets that date from the relay. An out-of-date relay sends its own UTC date instead: if your agents sit west of UTC, an evening dispatch carries tomorrow's date and the whole window lands a day late. The window you authored is fine; the date it is counted from is not. See The schedule date a legacy job is sent with.

The same date fills %SMA_MSLSAM_SCHEDULE_DATE%, so any path you build with it — including a path you read exit criteria or failure criteria from — is off by the same day on an old relay.

If the file arrives and settles inside the window, the job finishes successfully. Otherwise it's marked Failed, and the job's exit code tells you why — 1 means the window closed with no file, 2 means the folder doesn't exist.

As with the other LSAM job types, the form won't stop you from saving an invalid value. A blank or over-long file name, a stray ", an out-of-range offset, or an end offset earlier than the start fails when the job is dispatched, not while you edit.

On a UNIX/Linux LSAM machine

UNIX - File Arrival is the same idea with UNIX path rules. The window is authored with the same Day Offset and Time pair, and the same relay-date caution above applies.

Setting	Notes
Machine name	The UNIX/Linux LSAM machine to watch on; must match the name registered with the relay.
Batch user	The UNIX Batch User connection the job runs as. Required — unlike Windows, there is no "run as the agent's own account" option — and it has to be able to read the file.
File name	Absolute path of the file to watch for, up to 255 characters. Wildcards *, ? and [...] are allowed in the file-name part; matching is case-sensitive and files whose names start with a dot are skipped. The directory part is taken literally, must already exist, and must not contain spaces.
Start / end offset	As Windows. Leave both at zero to check whether a matching file exists right now.
File size stable time	Seconds to wait before re-checking the file's size, to confirm it's fully written. Defaults to 5.
Include subdirectories	Also search subdirectories of the given directory. Off by default.

Some characters can't appear in the path at all

` $ " \ ; | & < > ( ) ' are refused anywhere in the path, and spaces are refused in the directory part. Classic accepts them; Continuum doesn't, because an older UNIX agent hands the name to a shell when it searches. If you need one of these characters in a watched path, this job type can't do it. The refusal happens at dispatch, naming the field.

Two differences from Windows worth knowing

• Stability is judged on size alone. The Windows agent also waits for the timestamps to settle; the UNIX agent compares only the length. A file whose timestamps move but whose size holds will satisfy a UNIX watch.
• A file that keeps growing keeps the job waiting, even past the end of the window.

Its exit codes are 0 matched, 1 no match or unreadable, 2 directory doesn't exist, 3 the file was last modified outside the window, and -1 the end offset was earlier than the start.

Hand the file on to the next job

Once either type matches, the path it matched is recorded on the job. It shows on the job's Summary → Completion as Arrived File, and five properties carry it into the events and notifications that job fires — the whole path, its directory, the file name, the file name without its extension, and the extension.

That is how a downstream job gets told which file turned up, rather than being handed the pattern that found it. A $JOB:ADD or a notification fired from the File Arrival job can read [[$ARRIVED SHORT FILE NAME]] and pass the real name along.

Neither type offers an exit criteria table: the watcher's exit code is the verdict, so only 0 succeeds.

Run a T-SQL script on a SQL LSAM machine

On a SQL LSAM machine, the MS SQL Script job type runs T-SQL against SQL Server. Pick it the same way as the command job types, under Integration.

Two job types share this name

MS SQL Script also exists under Database, from the SQL Database Executor plugin. That one runs on a Universal Agent and needs a saved SQL Server connection. The one described here runs on an existing SQL LSAM machine through the relay. The plugin named beside each is what tells them apart.

You supply the script one of two ways, and exactly one of them:

• SQL Script Statements — the T-SQL, typed into the job.
• Script File Path — the path to a .sql file that already sits on the machine. This is a path on that machine, not a script from the script library.

Leaving both blank, or filling both in, saves cleanly and then fails when the job runs.

Setting	Notes
Machine name	The SQL LSAM machine to run on.
Server Name\Instance	The SQL Server host, or HOST\INSTANCE for a named instance.
Database Name	The database to start in. Blank uses the server's default for the login.
Batch user	A SQL Batch User connection. Blank runs the job as the agent's own service account.
Windows Authentication	On, the job reaches SQL Server as the impersonated Windows account instead of with a SQL Server login and password.
Encrypt Connection	On by default. See the caution below.
Use Exit Code From Script Result	Makes the script's own result the job's exit code. Only works with SQL Script Statements — it does nothing when you use a script file.
Redirect File Path	Writes the script's output to a file on the machine.
Other Options	Extra sqlcmd switches, passed through as typed.
Environment variables	Name/value pairs for the script's process. A name with a blank value is not sent.

This job type does have exit criteria, and OpCon Continuum always evaluates them itself — the SQL agent has no way to receive a criteria table, so it is the only legacy platform where that is true of every table. See Set exit criteria.

Know which code you are writing conditions against. With Use Exit Code From Script Result off, sqlcmd exits 0 on success and 1 on an error, which is the whole range available to a table. Turning it on makes the script's own result the exit code, which is what makes criteria worth setting on this type.

Encrypt Connection is on by default

With it on, SQL Server has to present a certificate the machine trusts. Against a server that does not, the job dispatches cleanly and then fails reaching the database — so it looks like a job failure, not a setup problem. Either get a trusted certificate onto SQL Server or turn the setting off.

A SQL machine can never take part in a file transfer, so it does not appear in the pickers of the job type below.

Transfer a file between two LSAM machines

The SMAFT File Transfer job type moves a file from one legacy machine to another — Windows to UNIX, UNIX to Windows, or either to itself — using SMA's own file-transfer protocol. Pick it under Show Job Types → File Transfer → SMAFT File Transfer.

It works differently from every other job type here in one respect: you don't choose the machine it runs on. You name both ends, and Start Transfer On decides which of the two does the work.

Setting	Notes
Source Machine / Destination Machine	The two ends. Each list offers only machines whose FT Role permits that direction, so a machine missing from a list has a role that excludes it — including the default, None, which an administrator has to change before the machine takes part in any transfer.
Source File / Destination File	Full path and file name at each end. Wildcards * and ? are allowed and transfer more than one file. No double quotes.
Source User / Destination User	The Batch User connection for that end, filtered to that machine's platform. A Windows end may be left blank to run as the agent's service account; a UNIX end must have one.
Source / Destination Data Type	Text, ASCII, or Binary. Text and ASCII translate line endings between platforms; Binary copies bytes unchanged and must be set on both ends. Text (the default) is accepted whichever platform runs the job — a transfer failing on an Unsupported Data Type from a UNIX end means the platform predates that fix, not that the setting is wrong.
Start Transfer On	Destination (the default) means the destination pulls from the source. Source means the source pushes — and that needs full file-transfer support on both machines.
If File Exists	What to do when the destination file is already there: don't overwrite (the default), overwrite, back up then overwrite, append, or back up then append.
Delete Source File	Delete the source after a successful transfer. Only No is available unless both machines are Windows.
Maximum Transfer Rate	A bandwidth cap chosen from fixed steps in kbit/s, not a number you type. >2048 (the default) means uncapped.
Compression / Encryption / TLS Security	Each is Required, Preferred, or None. Fail If Preferred Settings Not Satisfied decides whether a silent downgrade from Preferred fails the job.

Before you start: both machines need a file-transfer endpoint — an address, a port, and a role — set by an administrator. A Universal Agent has none and can never take part. Ask your administrator to give each machine an endpoint before you build the job.

As you fill the two machines in, the editor shows 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 for this job type, and offers no pool and no legacy agent group — change Start Transfer On or either machine and the assignment follows. Four mistakes are caught while you edit rather than at dispatch: a missing machine, Binary on only one end, the same file on the same machine at both ends, and a stale machine assignment.

A transfer waits on the other machine, and forcing it won't help

If the machine at the other end is offline, marked out of service, or unreachable, the job holds until it comes back — and unlike every other legacy job, force-start will not push it through. There is no file-transfer server at the far end to connect to, so forcing would only turn a wait into a failure.

There is also no exit-criteria setting: whatever the file-transfer agent reports is the job's outcome. So check the destination file, not just the job status — particularly on a wildcard transfer, where a partial match still completes. For the full parameter reference and the rules that fail a dispatch, see SMAFT File Transfer job.

Good to know

• These run through the relay on your existing LSAM machines, not the Universal Agent. If a command reports "no agent available," it's usually relay or machine connectivity; check with your administrator.
• On Windows LSAM, a job runs as the batch user you attach, or as the agent's own service account when you attach none. Per-job environment variables are supported; embedded scripts are not on the command job, so put your logic in the program or a script that already exists on the machine.

Related topics

• Legacy LSAM connectors (UNIX/Linux and Windows) — full configuration reference and troubleshooting
• SMAFT File Transfer job — the cross-machine transfer job type in full
• Prepare agents for connectors (Administrator)
• Respond to a failed connector job (Operator)