Procedure

8 minute readReference

createProcedure

Creates a new procedure for an existing project.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

credentialName

String

The name of a credential to attach to this procedure.

description

String

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

jobNameTemplate

String

Template used to determine the default name of jobs launched from a procedure.

resourceName

String

The name of the default resource for this procedure.

timeLimit

String

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

timeLimitUnits

TimeLimitUnits

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

workspaceName

String

The name of the default workspace for this procedure.

Positional arguments

projectName, procedureName

Usage

ec-perl

$cmdr->createProcedure(<projectName>, <procedureName>, {<optionals>});

ectool

ectool createProcedure projectName, procedureName, [optionals]

createStep

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}

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

stepName

String

(Required) Name of the step; must be unique within the procedure.

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

afterProcedureStep

String

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

alwaysRun

Boolean

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

beforeProcedureStep

String

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

broadcast

Boolean

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

String

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

comment

String

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

condition

String

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

String

The name of the credential object.

description

String

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

errorHandling

ErrorHandling

Specifies error handling for this step.

exclusive

Boolean

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

ExclusiveMode

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.

logFileName

String

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

parallel

Boolean

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

postProcessor

String

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

precondition

String

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.

releaseExclusive

Boolean

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

ReleaseMode

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.

resourceName

String

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

shell

String

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

subprocedure

String

Name of a procedure to invoke during this step.

subproject

String

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

timeLimit

String

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

timeLimitUnits

TimeLimitUnits

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

workingDirectory

String

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

String

The name of the workspace.

Positional arguments

projectName, procedureName, stepName

Usage

ec-perl

$cmdr->createStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

ectool

ectool createStep projectName, procedureName, stepName, [optionals]

deleteProcedure

Deletes a procedure, including all steps.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

Positional arguments

projectName, procedureName

Usage

ec-perl

$cmdr->deleteProcedure(<projectName>, <procedureName>);

ectool

ectool deleteProcedure projectName, procedureName

deleteStep

Deletes a step from a procedure.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

stepName

String

(Required) Name of the step; must be unique within the procedure.

Positional arguments

projectName, procedureName, stepName

Usage

ec-perl

$cmdr->deleteStep(<projectName>, <procedureName>, <stepName>);

ectool

ectool deleteStep projectName, procedureName, stepName

getProcedure

Finds a procedure by its name.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

Positional arguments

projectName, procedureName

Usage

ec-perl

$cmdr->getProcedure(<projectName>, <procedureName>);

ectool

ectool getProcedure projectName, procedureName

getProcedures

Retrieves all procedures in a project.

Arguments

Argument Name Type Description

projectName

String

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

Positional arguments

projectName

Usage

ec-perl

$cmdr->getProcedures(<projectName>);

ectool

ectool getProcedures projectName

getStep

Retrieves a step from a procedure.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

stepName

String

(Required) Name of the step; must be unique within the procedure.

Positional arguments

projectName, procedureName, stepName

Usage

ec-perl

$cmdr->getStep(<projectName>, <procedureName>, <stepName>);

ectool

ectool getStep projectName, procedureName, stepName

getSteps

Retrieves all steps in a procedure.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

Positional arguments

projectName, procedureName

Usage

ec-perl

$cmdr->getSteps(<projectName>, <procedureName>);

ectool

ectool getSteps projectName, procedureName

modifyProcedure

Modifies an existing procedure.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

credentialName

String

The name of a credential to attach to this procedure.

description

String

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

jobNameTemplate

String

Template used to determine the default name of jobs launched from a procedure.

newName

String

The new name for an existing object that is being renamed.

resourceName

String

The name of the default resource for this procedure.

timeLimit

String

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

timeLimitUnits

TimeLimitUnits

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

workspaceName

String

The name of the default workspace for this procedure.

Positional arguments

projectName, procedureName

Usage

ec-perl

$cmdr->modifyProcedure(<projectName>, <procedureName>, {<optionals>});

ectool

ectool modifyProcedure projectName, procedureName, [optionals]

modifyStep

Modifies an existing step.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

stepName

String

(Required) Name of the step; must be unique within the procedure.

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

afterProcedureStep

String

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

alwaysRun

Boolean

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

beforeProcedureStep

String

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

broadcast

Boolean

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).

clearActualParameters

Boolean

If true, the step should remove all actual parameters.

command

String

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

comment

String

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

condition

String

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

String

The name of the credential object.

description

String

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

errorHandling

ErrorHandling

Specifies error handling for this step.

exclusive

Boolean

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

ExclusiveMode

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.

logFileName

String

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

newName

String

The new name for an existing object that is being renamed.

parallel

Boolean

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

postProcessor

String

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

precondition

String

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.

releaseExclusive

Boolean

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

ReleaseMode

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.

resourceName

String

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

shell

String

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

subprocedure

String

Name of a procedure to invoke during this step.

subproject

String

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

timeLimit

String

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

timeLimitUnits

TimeLimitUnits

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

workingDirectory

String

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

String

The name of the workspace.

Positional arguments

projectName, procedureName, stepName

Usage

ec-perl

$cmdr->modifyStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

ectool

ectool modifyStep projectName, procedureName, stepName, [optionals]

moveStep

Moves a step within a procedure.

Arguments

Argument Name Type Description

projectName

String

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

procedureName

String

(Required) Name for the procedure; must be unique within the project.

stepName

String

(Required) Name of the step; must be unique within the procedure.

beforeStep

String

The name of the step before which stepName should appear. Blank to move the step to the last position.

Positional arguments

projectName, procedureName, stepName

Usage

ec-perl

$cmdr->moveStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

ectool

ectool moveStep projectName, procedureName, stepName, [optionals]