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.
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:
- Go to Workflows and open the workflow you want to edit.
- Add a job: on an empty workflow select First Job, otherwise select New Job (Null) in the tool panel on the left of the editor.
- In the job editor, select the Job Definition tab.
- In the Job Type list, choose Run Command.
- Under Job Parameters, in Command, enter the command to run.
- Set any optional settings (see below).
- Select Save.
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
3for "nothing to do". Add an exit criterion so3isn't a failure — but read the operator the right way round: a condition that matches means the job failed, so Equal To5fails the job on5. To fail on anything but0and3, that's four conditions: Less Than0, Equal To1, Equal To2and Greater Than3. - The command exits
0and prints an error. Add an output-parsing rule — ContainsERROR, set exit code8— then an exit criterion Greater Than or Equal To8to turn that into a failure. The rule alone only changes the code the job reports; the criterion is what fails it.
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 (after any output-parsing rule has set it) fails the job. Turn off and the exit code never fails it. Ignored when Exit Criteria are set. |
| Exit Criteria | Up to five exit-code conditions that mark the job failed. If any one matches, the job fails. |
| Output Parsing | Up to five rules that search the job output for text and set an exit code, which the exit criteria then judge. |
- 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.
- Every Run Command job has a fixed one-hour timeout, and no setting changes it. At the hour the agent stops the command, and a job the agent stops always fails, whatever your exit criteria say. A job that is stopped this way, whether by the timeout or by a cancel, reports exit code
128. Kill does not stop the command on a Universal Agent sooner. - Exit Criteria here follow the basic model of a legacy LSAM command job: a condition that matches fails the job. The legacy job types also offer an Exit Criteria Result of Finish OK, a Range operator and up to 20 conditions; Run Command offers none of those.
Related topics
- Run Command job — full configuration reference and troubleshooting
- Run a script (Builder)
- Respond to a failed connector job (Operator)