The Job Step Execution Environment

3 minute read

Terms and definitions

Various factors influence job step execution. Both a job step and its postprocessor (if any) run in the same environment, except shell. The shell used to run a command comes from what is specified in the step. If a shell is not specified on the step, the shell specified on the resource is used— this is also the same shell used for running the postprocessor.


The machine where a job step is executed is determined by the resource specified in the corresponding procedure step. If a pool is specified in the procedure step, CloudBees Flow picks a specific resource from that pool. A job step can determine its actual resource by querying the property /myResource/resourceName or assigned resourceName property on the job step. The host where a step is expected is /myResource/hostName. If the resource is a proxy agent, this property contains the name of the proxy target. The agent host name is in /myResource/proxyHostName.

OS-level access control

For its resource, a job step executes under the same account as the CloudBees Flow agent. You may want to contact CloudBees technical support for help configuring CloudBees Flow agents. Basically, the agent needs to know what account it will run as, and Windows agents require additional setup if impersonation is used. If using impersonation, the job step runs under the credential effectively attached to the step.

Environment variables

For its resource, a job step inherits environment variables from the CloudBees Flow agent. The agent’s environment variables can be configured as part of the agent configuration. In particular, the PATH environment variable typically includes the CloudBees Flow installation directory for easy access to applications such as ectool and postp (the CloudBees Flow postprocessor).

Working directory

The default job step working directory is the top-level directory in the job’s workspace. However, you can configure the working directory with a property on the procedure step. When you run on a proxy agent, the step actually runs on the proxy target, in the working directory specified in the step. If the working directory is not specified, the step runs in the UNIX path to the workspace.

Standard I/O

Standard job step output and errors are both redirected to the step log file.

CloudBees Flow access

For easy access to CloudBees Flow, the following environment variables are set automatically for a job step:

COMMANDER_HOME A variable whose value is the base installation directory for an agent. On Windows, this directory is typically C:\Program Files\Electric Cloud\ElectricCommander. On UNIX platform, this directory is typically /opt/electriccloud/electriccommander/.

COMMANDER_SERVER IP address for the CloudBees Flow server machine.

COMMANDER_PORT Port number for normal communication with the CloudBees Flow server.

COMMANDER_PLUGINS (configurable) The directory where installed plugins live (for example, C:\Documents and Settings\All Users\Application Data\Electric Cloud\ElectricCommander\Plugins )

COMMANDER_HTTPS_PORT Port number for secure communication with the CloudBees Flow server.

COMMANDER_JOBID Unique identifier for the job containing the current job step.

COMMANDER_JOBSTEPID Unique identifier for this job step.

COMMANDER_SESSIONID CloudBees Flow session identifier for the current job, which allows ectool to access CloudBees Flow with job associated privileges, without an additional login.

COMMANDER_WORKSPACE_UNIX Absolute path to the workspace directory for this job, in a form suitable for use on UNIX machines.

COMMANDER_WORKSPACE_WINDRIVE Absolute path to the workspace directory for this job, in a form suitable for use on Windows, and starting with a drive letter.

COMMANDER_WORKSPACE_WINUNC Absolute path to the workspace directory for this job, in a form suitable for use on Windows,specified using UNC notation.

COMMANDER_WORKSPACE Absolute path suitable for accessing the top-level workspace directory for this job on this machine. On a UNIX machine, this has the same value as COMMANDER_WORKSPACE_UNIX. For Windows, it is the same as COMMANDER_WORKSPACE_WINUNC.

COMMANDER_WORKSPACE_NAME This is the name of the workspace on the CloudBees Flow server.

These environment variables allow you to invoke ectool without specifying a --server argument. They also provide a context for accessing properties in ectool. For example, " ectool getProperty foo " looks for the property named "foo" on the current job step. Environment variables provide ectool with a session including all user privileges associated with the job.

Also, if the resource is a proxy agent, these environment variables are available in the step’s environment on the proxy target.