Run command or local script
Runs a command on the Clarive server itself, under the account the server process runs as, with the
job directory available through ${job_dir}. Output is streamed into the job log as it arrives, and
the return code plus the command output decide whether the job carries on or stops.
Reach for it for anything that belongs on the Clarive side: packaging what a checkout produced, calling a command line client, running a build in the job workspace. When the work belongs on a target machine, use Run a Remote Script, which is this form plus a server picker. For a file operation with backup and rollback behaviour built in, use Ship File Remotely instead of scripting a copy.
Fields¶
Command or Path¶
The command line to run, or the path to a script. It expands ${var} against the
stash before anything runs. A name the stash cannot resolve is left in the text
literally as ${name} rather than becoming an empty string, so a typo is passed to the shell
verbatim.
Whether a shell is involved depends on the Arguments grid. With the grid empty, the whole line is
handed to a shell, so cd ${job_dir} && tar czf out.tgz . behaves as you would type it at a prompt.
With even one argument row present, the command is executed directly and nothing is interpreted:
&&, pipes, redirections, ~ and wildcards all arrive at the program as literal text, and the first
word has to be a real executable rather than a shell builtin.
Options¶
A tab panel with three tabs, none of which most commands need.
Arguments¶
One argument per row. Add appends a row prefilled with ., Delete removes the selected row, and
a single click edits a row. Each row expands ${var}.
Adding a row changes how the command is run, as described above. If you want shell syntax, keep this
grid empty and write the arguments into Command or Path.
Environment¶
Environment variables for the command, written as YAML key-value pairs:
MY_ENV_VAR: "myvalue"
BUILD_ID: "${job_name}"
These are layered on top of the environment the Clarive server process already has, so the command
still sees PATH and everything else and you only need to list what you are adding or overriding.
An empty tab opens with a few commented example lines already in it. Comments are dropped when the
form is saved, so leaving that text untouched stores nothing. Malformed YAML raises a YAML Error
dialog and blocks the save until you correct it. Reopen the form and your keys come back sorted
alphabetically rather than in the order you typed them.
Output Files¶
Paths to log or report files the command writes. After a successful run, each one is read and attached to the job log as a separate entry named after the file.
A path that does not exist is skipped without a warning, so a typo here looks identical to a command that produced no log.
Publishing only happens on the success path, which means a zero return code that no Return Codes
range claimed. A non-zero code skips the publishing step whatever Errors is set to, warn and
silent included, which is exactly the opposite of when you want the log. To get a file off a failed
command, wrap the step in a TRY statement and attach the file yourself from
the recovery branch with Publish local file to log.
There is no size limit. Attaching a multi-megabyte build log puts the whole thing in the job record.
New rows are prefilled with whatever is in Home Directory, or with ${job_dir}/${project}/file.log
when that is empty.
Home Directory¶
The directory to change into before running, and back out of afterwards. The path is expanded first,
then checked: a path that does not exist fails the step with Could not change dir to directory
before the command runs at all.
The check only asks whether the path exists, not whether it is a directory. Point it at a file and the check passes, the change of directory quietly fails, and the command runs in the job's current directory with no complaint.
Left blank, the command runs in whatever directory the job is currently using.
Stdin¶
This field has no effect on a rule built in the designer. Whatever you type here is saved with the op
and never delivered to the command, so a script that blocks waiting for input will keep blocking
until the step times out. Feed input through a file and a redirection in Command or Path instead,
or have the script read from a path you pass as an argument.
Log Display¶
Replaces the command text in the Running command, Finished command and Error running command
headline entries. Set it when the command line carries a password or is too long to read in the
monitor.
This masks the headline only. The detail attached to the Running command entry still lists the real
command and every argument, so treat it as a readability feature and not as a secret-hiding one.
Credentials belong in variables or in resource attributes.
Left blank, the headline shows the command followed by its arguments.
Errors¶
How the return code is treated. The default is fail.
| Errors | A non-zero return code |
|---|---|
fail |
logs an error and stops the job |
warn |
logs a warning and carries on |
custom |
is looked up in the Return Codes ranges below |
silent |
is recorded at debug level only |
A command that could not be started at all, or that was killed by a signal, reports 255.
warn and silent decide how loudly the failure is reported, nothing more. A non-zero return code
always ends the step on the error path, so the Finished command entry, the Output Files
publishing and the whole Output pattern scan are skipped no matter which of the four you pick.
Return Codes¶
Three text boxes, shown only when Errors is set to custom.
Ok, Warn and Error each take a comma-separated list of numbers and ranges: 0, 2,4,8, 4-8
for the inclusive span, 8- for eight and above, -3 for three and below. Comparison is numeric.
They are evaluated as Warn, then Error, then Ok, and the last match wins, so Ok overrides the
other two. Putting 0 in Error makes a successful command fail the job.
Ok only downgrades the report to a debug entry. It does not put the step back on the success path,
so listing 0 in Ok costs you the Finished command line, the output files and the Output
pattern scan on every clean run. Leave Ok empty unless you have a non-zero code to forgive.
A non-zero return code that matches none of the three ranges is swallowed whole: no log entry at any
level, no failure, and the success path is skipped anyway. When you use custom, give Error a
catch-all such as 1- and name the codes you tolerate in Warn, so that nothing falls through
unreported.
Output¶
Four tabs of regular expressions matched against the combined standard output and standard error of
the command. Each tab is a grid with Add and Delete. New rows arrive prefilled with .*, which
matches everything, so a forgotten empty row on the Error tab fails every run.
| Tab | Effect when a pattern matches |
|---|---|
Error |
logs an error entry with the full output attached, and stops the job |
Warn |
logs a warning entry with the full output attached |
OK |
logs a note and suppresses the Error tab for this run |
Capture |
logs nothing of its own and exists to pull values into the stash |
Patterns are plain regular expressions. To add flags, write the pattern as !!pattern!!i.
The Error tab behaves differently here than it does on the remote version of this op: a match stops
the job whatever Errors is set to. Setting Errors to warn or silent tolerates a bad return
code, it does not tolerate a bad line of output. Use the Warn tab for text you want noticed but not
acted on.
The OK tab is scanned first and stops at its first match. Error and Warn then run every pattern
in their grid, so several can match and each produces its own entry.
None of these tabs are consulted when the return code already triggered the error path. That is the
usual reason a Capture pattern produces nothing: the command failed, so its output was never
scanned.
Named captures¶
A named group in any of the four tabs writes a stash variable. A pattern of
^Built (?<artifact_name>\S+)$ leaves artifact_name in the stash for later ops to read.
Only one pattern's captures survive. The tabs are scanned as OK, Error, Warn, Capture, and
each match replaces the whole set left by the previous one, including replacing it with nothing when
the matching pattern has no named groups. Keep your named groups on a single pattern on the Capture
tab, which is scanned last.
What the step returns¶
Set a Return Key in the op properties panel to keep the result. You get a value with output
holding the combined output text, rc holding the return code and ret holding a copy of rc,
readable as ${myresult.rc}. Set the return key to = instead of a name and those three land at the
top of the stash as ${output}, ${rc} and ${ret}, overwriting anything already parked under
those names.
You get the result even on the paths that logged nothing, so a Return Key is the only way to read a
return code that custom ranges swallowed.
The Timeout property in the same panel caps the run in seconds. When it expires the step ends with
a timeout error, which is not the same as the command being stopped: the process is left to run on
and finish in the background. Left at zero the command runs until it finishes on its own, so an
interactive command that waits for input will hang the job.
Combining with other ops¶
Run Init Job Home first if you are going to write into ${job_dir}, and
Checkout Job Environment (all repos) to put the source there.
Feed a generated file to Ship File Remotely to push the result to a target,
or to Publish local file to log to attach a single artifact without
the all-or-nothing behaviour of Output Files.
Branch on a captured value with IF var condition THEN, or turn the whole output into a decision with EVAL JavaScript.
Clean up afterwards with Delete Local Directory or Delete Local File.
Examples¶
Package what the checkout left in the job directory. The grid stays empty so that && works.
Command or Path cd ${job_dir}/${project} && tar czf ../myapp.tgz .
Errors fail
Run a build tool with arguments in the grid, so no shell is involved. The build log reaches the job only on the runs that exit zero.
Command or Path /usr/local/bin/mybuild
Arguments --project
${project}
--verbose
Environment BUILD_ID: "${job_name}"
Home Directory ${job_dir}/${project}
Output Files ${job_dir}/${project}/build.log
Errors fail
Run a checker that signals "nothing to do" with exit code 2, and capture the version it prints.
Ok is left empty on purpose: a code listed there would put the step on the error path and the
Capture pattern would never be scanned.
Command or Path /opt/tools/check.sh ${release.title}
Errors custom
Return Codes Warn: 2,3-5 Error: 1,6-
Output > Capture version:\s*(?<checked_version>[\d.]+)