Run a command

The Run Command job runs a command line on the agent: call a utility, trigger a batch file, kick off an existing process. It's built in, so there's nothing to set up.

What this solves

An existing program or batch file needs to run as a step in a larger process, on schedule and with its result captured. Triggering it by hand, or with a stray scheduled job on some server, is the manual glue that silently breaks and leaves no record.

Use it when

• You need to run a single program or shell command as a step in a workflow.
• You want to use shell features like pipes or redirects.

Add a Run Command job to a workflow

To add a Run Command job, 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 Script, select Run Command.
6. Under Job Parameters, in Command, enter the command to run.
7. Set any optional settings (see below).
8. Select Save & Close.

Decide what counts as failure

By default the job fails on any non-zero exit code. When the command's own convention is different, say so instead of accepting the default:

• The command exits 3 for "nothing to do". Add an exit criterion so 3 isn't a failure — but read the operator the right way round: a condition that matches means the job failed, so Equal To 5 fails the job on 5. To fail on anything but 0 and 3, that's two conditions: Less Than 0 and Greater Than 3.
• The command exits 0 and prints an error. Add an output-parsing rule — Contains ERROR, set exit code 8 — then an exit criterion Greater Than or Equal To 8 to turn that into a failure. The rule alone only changes the code the job reports; the criterion is what fails it.

Output parsing sees only the first and last 512 KB of each stream

A job that prints more than 1 MB has the middle of its output dropped, and text that appears only there won't match. The job output says so when it could have changed the result. Matching is also case sensitive, and * and ? are the only wildcards — it is not a regular expression.

Settings

Setting	Notes
Command	The command line to run. Required.
Arguments	Arguments appended to the command.
Working Directory	Where the command runs. Defaults to the agent's working directory.
Environment Variables	Extra environment variables for the command.
Run via Shell	On by default: runs through the system shell so pipes and redirects work. Turn off to run a program directly.
Fail on Error	On by default: a non-zero exit code fails the job. Turn off and the exit code never fails it.
Exit Criteria	Up to five exit-code conditions that mark the job failed. Set any and Fail on Error no longer applies.
Output Parsing	Up to five rules that search the job output for text and set an exit code, which the exit criteria then judge.

Good to know

• The command runs on the agent, so the program must exist there. If it can't be found, check the command and working directory, or ask your administrator about the agent.
• For security, the command can't read the agent's stored secrets from its environment (variables named like a password or secret are filtered). Pass values you need as Environment Variables, or use a connection-based connector for credentials.
• For multi-line logic, use Run a script instead.
• A job the platform stops — a timeout, or a cancel — always fails, whatever your exit criteria say.
• Exit Criteria and Output Parsing work the same way here as on a legacy Windows LSAM command job, so the same settings mean the same thing on both.

Related topics

• Run Command job — full configuration reference and troubleshooting
• Run a script (Builder)
• Respond to a failed connector job (Operator)