Remote Execution

The remote execution task executes commands, scripts or programs on one or more hosts.

The Command

The command field takes the command and arguments to run on the remote host. The command field is process by the template engine to allow the command or its arguments to passed.

The behavior of the command field differs between operating systems. On UNIX systems, the command is executed as if run as:

/bin/sh -c "<contents of command field>"

On a Windows system and when the "Run on logged in user's desktop" is NOT checked, the command is run as if executed as:

cmd /S /C "<contents of command field>"

Using the CreateProcessAsUser() system call.

On a Windows system when the "Run on logged in user's desktop" is checked, the contents for the command field are passed (after expansion by the template engine) to CreateProcessAsUser() with no command shell involved.

Run As

The user to run the command as. The user value is processed by template engine, allowing the user to be selected at runtime. The resulting value must be a pre-defined Situate user as enumerated under the Service Account list in the object browser.

If the Run As field does not expand to a valid Situate user, the task will fail with an unknown user exception

When a task executes on a given computer, the best identity among those identities associated with the Situate user will be used to to execute the command. For more information about how Situate chooses native identities. See the section on Native Identities.

Success Codes

The success codes field contains a comma- or space-separated list of exit statuses. If the command exits with on of these values, it is assumed the task succeeded. If not, it's assumed the task failed.

The success codes are ignored whenever "Wait for completion" is unchecked.

Wait For Completion

If checked, Situate will wait for the command to run to completion and return an exit status. This exit status is then checked against the success codes to determine success or failure.

If unchecked, Situate will declare success if it can simply start the process. It does not wait for the process to complete and allows the workflow to immediately continue. This desirable when remote commands are used to start long running processes. In this case, the success codes are ignored.

Keep Logfile

If checked, Situate will keep the output of the process. The output will be made available through the viewer by clicking on the "Log File" link in the task log.

Retries

Specifies the number of times a task should be re-executed until it succeeds.

Concurrency

Specifies the number of concurrent agents the task is executed on at any given time. For example, a concurrency of three means the task will be executed on three agents at a time.

Assets

A list of agents upon which the command should be executed. Agents must be defined in the object browser before they can be used. See agents.

Each entry in the agents table is processed through the template engine. It is therefore possible to pass the name of an agent as a variable. If the variable is a list variable, the list is expanded into the table, meaning the command will run for each agent in the list as well as any others in the table.

Environment

A list of environment variables added to the base set (see below) for the running process. Each variable and value in the table is processed through the template engine to allow variables to be set at runtime.

Environment Variables on UNIX Systems

On a UNIX system, environment variables are handled as follows: First, a posix borne shell is created. This creates a base set of environment variables. The system's /etc/profile and the user's ~/.profile is NOT read. Next, each environment variable in turn is set. You can think of this as executing "X=Y ; export X", where X and Y are the variable and value being set, for each variable in the table.

ENV is a special environment variable. It may be used to replace the /etc/profile and/or ~/.profile mechanism. Situate does not execute the /etc/profile or ~/.profile when executing a command. This because workflows are carefully controlled, highly secure processes that require approval and auditing. If a particular user's ~/.profile is read, it creates a security hole -- allowing that user to change (possibly inadvertently) the behavior of a workflow.

Still, this behavior is nice to have. Consider the following... you are creating a set of workflows that compiles your program, runs it through unit testing, and then promotes it to a Q/A environement. It would be nice to have a protected file (perhaps under source control) that could be sourced by the shell to establish a common environment (set the compiler paths, classpaths, etc.) for each remote command run by these workflows. This can be accomplished by setting the ENV variable to the location of this file.

PWD The working directory for each task is set to / (root) by default. You can explicitly set the working directory of your command by setting the PWD variable.

The USER and HOME variables are typically set by the /etc/profile mechanism. Because script writers depend heavily on these variables, Situate sets these on your behalf.

Environment Variables on Windows Systems

On Windows systems, the base set of environment variables is created from the user's profile and systems settings using the same process used by the operating system (using CreateEnvironmentBlock()). Environment variables specified in the table either override or are added to these variables.