createStep

Back to index

Summary

Creates a new procedure step.

Fundamentally, CloudBees CD/RO supports three types of steps:

Command step: The step executes a command or script under the control of a shell program.
Subprocedure step: The step invokes another CloudBees CD/RO procedure. In this case, the step does not complete until all subprocedure steps have completed.
Custom step

You must specify a projectName, procedureName, and stepName.

projectName

Stringrequired

The name for the project that must be unique among all projects.

procedureName

Stringrequired

Name for the procedure; must be unique within the project.

stepName

Stringrequired

Name of the step; must be unique within the procedure.

actualParameter

Arrayoptional

Actual parameters passed to an invoked subprocedure.

afterProcedureStep

Stringoptional

If specified, the procedure step will be placed after the named procedure step.

alwaysRun

Booleanoptional

True means this step will run even if preceding steps fail in a way that aborts the job.

beforeProcedureStep

Stringoptional

If specified, the procedure step will be placed before the named procedure step.

broadcast

Booleanoptional

True means replicate this step to execute (in parallel) on each of the specified resources (that is, for a pool, run the step on each of the resources in the pool).

command

Stringoptional

Script to execute the functions of this step; passed to the step's shell for execution.

comment

Stringoptional

Script to execute the functions of this step; passed to the step's shell for execution.

condition

Stringoptional

A fixed text or text embedding property references that is evaluated into a logical TRUE or FALSE. An empty string, a 0 or false is interpreted as FALSE. Any other result string is interpreted as TRUE.

credentialName

Stringoptional

The name of the credential object.

description

Stringoptional

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

errorHandling

Stringoptional

Specifies error handling for this step.

Possible values: "abortJob", "abortJobNow", "abortProcedure", "abortProcedureNow", "failProcedure", "ignore", "retryOnError"

exclusive

Booleanoptional

True means the resource acquired for this step will be retained for the exclusive use of this job. This means 2 things: first, no other job will be able to use that resource, regardless of its step limit, until this job completes; second, future steps for this job will use the resource in preference to other resources, if this resource meets the needs of the steps and its step limit is not exceeded.

exclusiveMode

Stringoptional

Determines the mode to use when the step acquires a resource. If set to none, then the default behavior for the step applies. If set to job, then the resource will be retained for the exclusive use of this job. If set to step, then the resource will be retained for the exclusive use of this step and procedure it may call. If set to call, then the resource will be retained for the exclusive use of all steps within the current procedure call.

Possible values: "none", "job", "step", "call"

logFileName

Stringoptional

Name of the log file for a step; specified relative to the root directory in the job's workspace.

parallel

Booleanoptional

True means this step and all adjacent steps with the flag set will run in parallel.

postProcessor

Stringoptional

This command runs in parallel with the main command for the step; it analyzes the log for the step and collects diagnostic information.

precondition

Stringoptional

releaseExclusive

Booleanoptional

True means the resource acquired for this step will be no longer be retained for the exclusive use of this job when this step completes.

releaseMode

Stringoptional

Determines the mode to use when the step releases its resource. If set to none, the default behavior applies. If set to release, then the resource will be available for use by any job. If set to releaseToJob, then the resource will be available for use by any step in this job.

Possible values: "none", "release", "releaseToJob"

resourceName

Stringoptional

Name for the resource; must be unique among all resources.

shell

Stringoptional

Name of the shell program that will execute the command and postprocessor for the step.

subprocedure

Stringoptional

Name of a procedure to invoke during this step.

subproject

Stringoptional

Name of the project containing the procedure to invoke during this step.

timeLimit

Stringoptional

Maximum amount of time the step can execute; abort if it exceeds this time.

timeLimitUnits

Stringoptional

Units for step time limit: seconds, minutes, or hours.

Possible values: "hours", "minutes", "seconds"

workingDirectory

Stringoptional

Working directory in which to execute the command for this step. A relative name is interpreted relative to the root directory for the job's workspace.

workspaceName

Stringoptional

The name of the workspace.

Usage

Perl

$cmdr->createStep(
  "test-projectName", # projectName
  "test-procedureName", # procedureName
  "test-stepName" # stepName
  # optionals
);▼

ectool

ectool createStep \
  "test-projectName" `# projectName` \
  "test-procedureName" `# procedureName` \
  "test-stepName" `# stepName` \
  # optionals▼

Examples

Perl

Specifying most arguments to the Perl createStep API is fairly intuitive. Similar to any other API, key-value pairs are specified in a hash argument for all optional parameters. However, specifying actual parameters is a little different because they are not arbitrary key-values characterizing the step. Actual parameters are key-values characterizing actual parameters to the step. Refer to the following createStep request in XML:

<createStep> <projectName>MyProject</projectName>
 <procedureName>MyProcedure</procedureName> <stepName>Step1</stepName>
 <actualParameter> <actualParameterName>parm1</actualParameterName>
 <value>myval</value> </actualParameter> <actualParameter>
 <actualParameterName>parm2</actualParameterName> <value>val2</value>
 </actualParameter> </createStep>▼

Each actual parameter key-value is under an <actualParameter> element, which is codified in the optional arguments hash in the Perl API like this:

{… ⇒ …, actualParameter ⇒ [{actualParameterName ⇒ 'parm1', value ⇒ 'myval'}, {actualParameterName ⇒ 'parm2', value ⇒ 'val2'}], … ⇒ …}

In other words, the value of the actualParameter key in the optional arguments hash is a list of hashes, each representing one actual parameter. If the subprocedure call only takes one actual parameter, the value of the actualParameter key can be specified as just the hash representing the one parameter:

actualParameter ⇒ {actualParameterName ⇒ 'parm1', value ⇒ 'myval'}

For example:

$cmdr->createStep("Test Proj", "Run Build", "Common Cleanup", {subprocedure => "Delay",
   actualParameter => {actualParameterName => 'Delay Time', value => '5'}});▼

ectool

Specifying actual parameters in an ectool call is also different from specifying other arguments. Specify each key-value as an equal-sign delimited value:

ectool createStep … --actualParameter "Delay Time=5" "parm2=val2"

If the parameter name or value contains spaces, quotes are needed.

For example:

ectool createStep "Test Proj" "Run Build" "Compile" --command "make all"

ectool createStep "Test Proj" "Run Build" "Common Cleanup" --subprocedure "Delay"
  --actualParameter "Delay Time=5"▼