Step—create new or edit existing step

If you chose to create a step using the Plugin link, additional help is available in the Parameters section by selecting the ? icon. The Parameter section is populated according to the type you chose to create. Different step types require different information.

To create a new command or subprocedure step

Enter information into the fields as follows:

Field Name Description

General section (for all step types)

Name

Enter a name for the step that must be a unique name within the procedure.

Description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Command section (for command steps only)

Command(s)

A script to execute the step functions that is passed to the step’s shell for execution.

Resource

Enter a unique resource or resource pool name or click Browse to select a resource. If you leave this field blank, the procedure or project provides a default resource.

The job step must have the execute privilege on the resource or resource pool. If it does not, the job step will be canceled with an access denied error.
The resource or resource pool must be enabled. If the resource or pool is not enabled, no error is generated, and the step remains in the runnable state until the pool is enabled.

Postprocessor

If this field is empty, no postprocessor runs for the step. If this field is not empty, it specifies a command that is passed to the step’s shell for execution, analyzes the log file for the step, and collects diagnostic information for reporting. For more information, refer to Postprocessors: Collecting Data for Reports.

Subprocedure section (for subprocedure steps only)

Procedure

Displays the current project and procedure. Select Change to use the pop-up menu to select a new project or procedure.

Resource

Enter a unique resource name or click Browse to select a resource. If you leave this field blank, the procedure or project provides a default resource.

Parameters section (for subprocedure steps only)

This section expands automatically, entering the fields you need specifically for the Subprocedure you chose in the previous section. For additional help with field descriptions, select the ? icon, if available.

To toggle between the standard view and property view for this section, select the switch view Change view icon. This icon appears in the standard form when one or more of the parameter types are not Text entry or Text area. It appears in the custom form for all the supported parameter types when the form has at least one parameter.

Advanced section (for both command and subprocedure steps)

Precondition

By default, if this field is blank, the step has no precondition and will run when scheduled. Set this property to make a step wait until one or more dependent conditions are met. When a job step is eligible to transition from pending to runnable, a precondition is evaluated. A precondition is a fixed text or text embedding property reference that is evaluated to TRUE or FALSE. An empty string, a \"0\" or \"false\" is interpreted as FALSE. Any other result string is interpreted as TRUE. The step will block until the precondition is TRUE.

You cannot use timestamps in preconditions on any object that supports preconditions. This includes stages, gates, and tasks as well as procedures and process steps.

We recommend not using /increment when setting preconditions for pipeline objects or procedures.

Precondition example: Assume we defined these 4 steps:

Build object files and executables
Build installer
Run unit tests
Install bits on test system

Step 1 is an ordinary serial step. Steps 2 and 3 can run in parallel because they depend only on step 1’s completion. Step 4 depends on step 2, but not step 3. You can achieve optimal step execution order with preconditions:

Make steps 2-4 run in parallel.
Step 2 needs a job property set at the end of its step to indicate step 2 is completing ( set /myJob/buildInstallerCompleted to 1 ).
Set a precondition in step 4: $[/myJob/buildInstallerCompleted]

Run Condition

By default, if this field is blank the step will always run. This field accepts "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. A "0" or "false" is interpreted as FALSE. An empty string or any other result is interpreted as TRUE. The property reference can be a JavaScript expression, for example, this expression could test whether the name of a step is equal to the value of a property called "restartStep". $[/javascript (myStep.stepName == myJob.restartStep)]

Error handling

This field determines what happens to the procedure if the step fails.

The first choice, "procedure continues, but overall status will be error" means an error in the step does not abort the procedure; subsequent steps will run as usual. However, an error will be reflected in the overall outcome of the procedure. If this is the top-level procedure in the job, the job will have an error outcome.

If this is a subprocedure, the step invoking the subprocedure will have an error outcome, which still could cause the job to abort, depending on the error handling for that step.

The second choice for this field is "abort procedure but allow running steps to continue." In this case, if an error occurs, no new steps are initiated in this procedure except those where "always run" was selected. Any steps currently running are allowed to complete, then the procedure will abort and its outcome will be set to error as described previously.

Six error handling options are:

failProcedure —The current procedure continues, but the overall status is error (default).
abortProcedure —Aborts the current procedure, but allows already-running steps in the current procedure to complete.
abortProcedureNow —Aborts the current procedure and terminates running steps in the current procedure.
abortJob —Aborts the entire job, terminates running steps, but allows alwaysRun steps to run.
abortJobNow —Aborts the entire job and terminates all running steps, including alwaysRun steps.
ignore —Continues as if the step succeeded.

Time Limit

The maximum amount of time the step can execute. If the step exceeds this time, it will be aborted. Specify a number and then use the pull-down menu to select the "time units" of the number you specified.

Run in parallel

If this box is "checked," this step will run concurrently with any adjacent steps marked as parallel. If this box is not checked, the step will NOT run until all previous steps in the procedure have completed, and it will complete before any following steps execute.

Always run step

If a procedure is aborted (either because of an error in a step or because the job was aborted), under normal conditions no new steps will start in the procedure. However, if this box is "checked," the step will run even if the procedure is aborted. This facility is most commonly used for steps at the end of a job that generate reports or perform cleanup operations.

The Run Condition field is still evaluated and may cause the step to be skipped even if this box is checked.

Retain Exclusive

Select one of the following options:

None—the "default", which does not retain a resource.
Job—keeps the resource for the duration of the job. No other job can use this resource, regardless of its step limit, until this job completes or "Release Exclusive" is used in a step. Future steps for this job will use this resource in preference to other resources—if this resource meets the needs of the steps and its step limit is not exceeded.
Step—keeps the resource for the duration of the step.
Call—keeps the resource for the duration of the procedure that called this step, which is equivalent to 'job' for top level steps.

Workspace

Use this field to define a workspace for the step to use. You can either type-in a workspace name or click Browse to select a workspace. If you leave this field blank, the workspace is determined by the procedure or project.

These "Advanced" fields are used for command steps only

Broadcast

"Checking" this box means replicate the step to execute (in parallel) on each of the specified resources (for example, if a resource pool is specified, run the step on each resource in the pool).

Release Exclusive

Select one of the following options:

none —The "default"—no action if the resource was not previously marked as "retain".
release —Releases the resource at the end of this step. If the resource for the step was previously acquired with "Retain exclusive" (either by this step or some preceding step), the resource exclusivity is canceled at the end of this step. The resource is released in the normal way so it may be acquired by other jobs.
releasetojob —Allows a step to promote a Step exclusive resource to a Job exclusive resource.

Shell

This shell will be used to execute the step’s commands on a resource. For example, using sh or cmd /c, the agent saves the command block to a temporary file with a .cmd extension and runs it: sh foo.cmd or cmd /c foo.cmd If you do not specify a shell on a step, at step run-time the server looks at the resource shell. If a resource shell is not set, the shell line used by the agent is platform dependent: Windows: cmd /q /c "{0}.cmd" UNIX: sh -e "{0}.cmd" When you specify a shell (in the step or resource), and omit the cmd-file marker, the agent notices the omission and takes the correct action. For example: a user specifies sh -x. The agent converts this to sh -x "{0}.cmd" Two alternate forms of shell syntax where CloudBees CD/RO uses a "marker," {0}, as a placeholder for the command file argument:

< myShell > {0} < potential extra shell args > In this example, the command file is not meant to be the last argument in the final command line. For example, mysql -e "source {0}" This shell example runs the mysql command against this step’s command containing sql.
< myShell > {0} <. file extension > < potential extra shell args > In this example, the shell requires the command file to end in an extension other than .cmd. For example, powershell "& '{0}.ps1'" This shell example runs Microsoft PowerShell against this step’s command containing PowerShell commands.

When the agent parses the shell, it will parse the extension as everything after {0}. until it sees a space or non-alphanumeric character.

If your script uses International characters (non-ASCII), add the following block to the top of your ec-perl command block: use utf8; ` ElectricCommander::initEncodings`

Working Directory

The directory where the commands for this step execute. A relative name is interpreted relative to the root directory for the job workspace. If you leave this field blank, the step’s working directory will be the top-level directory in the job workspace.

If this step will run on a proxy resource, this directory must exist on the proxy target. The step will run in this directory on the proxy target.

Log File

The step’s log file name, specified relative to the root directory in the job workspace. If you leave this field blank, CloudBees CD/RO picks a unique name for the log file based on the step name.

Impersonation section (for both command and subprocedure steps)

Credential Project

By default, the Current project is used, or click Browse and select a different project.

Credential Name

If you select a credential in this field, the step runs under the account from that credential. This field is usually empty, which means a default credential is used. For more detailed information about credentials, refer to Credentials and user impersonation.

Select OK to create the step.

To edit an existing command or subprocedure step

You can modify any of your previously entered step information and add information to one or all of the four additional sections.

Attached Credentials

Select Attach Credential to retrieve an existing credential for this step. If you need to create a new attached credential, return to the Project Details page for this step.

Attached Parameter Credentials

Select Attach Parameter Credential to retrieve an existing parameter credential for this step.

Email Notifiers

Choose Create On Start Email Notifier or Create On Completion Email Notifier to go the respective page to create the email notifier you need.

Custom Step Properties

Choose from the Create Property, Create Nested Property, or Access Control links to add a custom property to this step. Each Property pop-up box has its own Help topic or go to the main Properties Help topic for more information. For more information about Access Control, go to the main Access control Help topic.

Select OK to save your modified step information.