Procedure Management

createProcedure

Creates a new procedure for an existing project.

You must specify projectName and procedureName.

Arguments Descriptions

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String
credentialName	(Optional) The name of the credential specified in one of these formats: relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object. absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object. Argument type: String
description	(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. The only HTML tags allowed in the text are: `<a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>` Argument type: String
jobNameTemplate	(Optional) Template used to determine the default name of jobs launched from a procedure. Argument type: String
resourceName	(Optional) The name of the default resource or pool used in steps run by this procedure. Argument type: String
timeLimit	(Optional) If no time limit was specified on the calling step, time limits are copied to the calling step from the procedure. If the procedure is called from `runProcedure` (or a schedule), the time limit acts as a global job timeout. The timer for the procedure starts as soon as the calling step or job becomes runnable (all preconditions are satisfied). Argument type: String
timeLimitUnits	(Optional) Time limit units are `hours\|minutes\|seconds`. Argument type: TimeLimitUnits
workspaceName	(Optional) The name of the default workspace used in steps run by this procedure. Argument type: String

projectName

The name of the project that contains this procedure. The name must be unique among all projects.

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

credentialName

(Optional) The name of the credential specified in one of these formats:

relative (for example, "cred1" )—The credential is assumed to be in the project that contains the requested target object.
absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the project for the target object.

Argument type: String

description

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

Argument type: String

jobNameTemplate

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

Argument type: String

resourceName

(Optional) The name of the default resource or pool used in steps run by this procedure.

Argument type: String

timeLimit

(Optional) If no time limit was specified on the calling step, time limits are copied to the calling step from the procedure. If the procedure is called from runProcedure (or a schedule), the time limit acts as a global job timeout. The timer for the procedure starts as soon as the calling step or job becomes runnable (all preconditions are satisfied).

Argument type: String

timeLimitUnits

(Optional) Time limit units are hours|minutes|seconds.

Argument type: TimeLimitUnits

workspaceName

(Optional) The name of the default workspace used in steps run by this procedure.

Argument type: String

Positional arguments

projectName, procedureName

Response

Returns a procedure element.

ec-perl

syntax: $<object>->createProcedure(<projectName>, <procedureName>, {<optionals>});

Example

$ec->createProcedure("Default", "Run Build", {resourceName => "Test Machine 1"});▼

ectool

syntax: ectool createProcedure <projectName> <procedureName> [optionals]

Example

ectool createProcedure "Default" "Run Build" --resourceName "Test Machine 1"▼

Back to top

createStep

Creates a new procedure step.

Fundamentally, CloudBees Flow 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 Flow procedure. In this case, the step will not complete until all subprocedure steps have completed.
Custom Step

You must specify a projectName, procedureName, and stepName.

Arguments Descriptions

projectName

The name of a project that must be unique among all projects.

Argument type: String

procedureName

The name for a procedure that must be unique within the project.

Argument type: String

stepName

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

Argument type: String

actualParameters

(Optional) Specifies the values to pass as parameters to the called procedure. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the called procedure. For more information about parameters, click here .

Argument type: Map

afterProcedureStep

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

Argument type: String

alwaysRun

(Optional) < Boolean flag - 0|1|true|false >. The default is false.

If this value is set to 1 or true, this step will run even if the job is aborted before the step completes. This is a useful argument for running a "cleanup" step that should run whether the job is successful or not.

Argument type: Boolean

beforeProcedureStep

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

Argument type: String

broadcast

(Optional) < Boolean flag - 0|1|true|false >. The default is false.

If this value is set to 1 or true, the same step is run the same step on several resources at the same time. The step is "broadcast" to all resources listed in the resourceName argument. This argument is applicable only to command steps.

Argument type: Boolean

command

(Optional) The command to run. This argument is applicable only to command steps.

Argument type: String

comment

(Optional) The script to execute the functions of this step, which are passed to the step’s shell for execution.

Argument type: String

commandFile

(Optional) Contents of the command file is read and stored in the "command" field. This is an alternative argument for command and is useful if the "command" field spans multiple lines. The commandFile value is the actual command file text. This argument is applicable to command steps only.

This option is supported only in Perl and ectool bindings—it is not a part of the XML protocol.

condition

(Optional) If empty or non-zero, the step will run. If set to "0", the step is skipped. A useful setting during procedure development or when re-running a job that has already completed some of the steps. Also, this argument is useful for conditional execution of steps based on properties set by earlier steps.

Argument type: String

credentialName

(Optional) The credential to use for impersonation on the agent.

Name of the credential in one of these forms:

Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.
Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

description

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

Argument type: String

errorHandling

(Optional) Determines what happens to the procedure if the step fails:

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.

Argument type: ErrorHandling

exclusive

(Optional) < Boolean flag - 0|1|true|false >.

If set to 1 or true, this step should acquire and retain this resource exclusively. The default is false.

When you set exclusive, exclusiveMode is set to "job".

Argument type: Boolean

exclusiveMode

(Optional) Use 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.

Argument type: ExclusiveMode

logFileName

(Optional) A custom log file name produced by running the step. By default, CloudBees Flow assigns a unique name for this file.

Argument type: String

parallel

(Optional) The value for parallel is a < Boolean flag - 0|1|true|false >.

If set, indicates this step should run at the same time as adjacent steps marked to run as parallel also. The default is to false.

Argument type: Boolean

postProcessor

(Optional) The name of a program to run after a step completes. This program looks at the step output to find errors and warnings. CloudBees Flow includes a customizable program called "postp" for this purpose. The value for postProcessor is a command string for invoking a post-processor program in the platform shell for the resource ( cmd for Windows, sh for UNIX).

Argument type: String

precondition

(Optional) By default, if the step has no precondition, it 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 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.

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 ( /myJob/buildInstallerCompleted=1 ).
Set a precondition in step 4: $[/myJob/buildInstallerCompleted]

Argument type: String

releaseExclusive

(Optional) < Boolean flag— 0|1|true|false >

This declares whether or not this step will release its resource, which is currently held exclusively. Setting this flag to "true" is the same as setting releaseMode to release.

Argument type: Boolean

releaseMode

(Optional) Use 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.

Argument type: ReleaseMode

resourceName

(Optional) Name for the resource that must be unique among all resources.

Argument type: String

shell

(Optional) Where shell is the name of a program used to execute commands contained in the "command" field. The name of a temporary file containing commands will be appended to the end of this invocation line. Normally, this file is a command shell, but it can be any other command line program. The default is to use the standard shell for the platform it runs on ( cmd for Windows, sh for UNIX). This is applicable to command steps only.

Argument type: String

subprocedure

(Optional) The name of the nested procedure to call when this step runs. If a subprocedure is specified, do not include the command or commandFile options.

Argument type: String

subproject

(Optional) If a subprocedure argument is used, this is the name of the project where that subprocedure is found. By default, the current project is used.

Argument type: String

timeLimit

(Optional) The maximum length of time the step is allowed to run. After the time specified, the step will be aborted. The time limit is specified in units that can be hours, minutes, or seconds.

Argument type: String

timeLimitUnits

(Optional) Specify hours|minutes|seconds for time limit units.

Argument type: TimeLimitUnits

workingDirectory

(Optional) The CloudBees Flow agent sets this directory as the “current working directory,” when running the command contained in the step. If no working directory is specified in the step, CloudBees Flow uses the directory it created for the job in the CloudBees Flow workspace as the working directory.

If running a step on a proxy resource, this directory must exist on the proxy target.

Argument type: String

workspaceName

(Optional) The name of the workspace where the log files for this step will be stored.

Argument type: String

Positional arguments

projectName, procedureName, stepName

Response

Returns a step element.

ec-perl

syntax: $<object>->createStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

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. See 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'}

Example

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

ectool

syntax: ectool createStep <projectName> <procedureName> <stepName> [optionals]

Specifying actual parameters in an ectool call is also different than 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.

Examples

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

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

Back to top

deleteProcedure

Deletes a procedure, including all steps.

You must specify a projectName and procedureName.

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String

Arguments

Descriptions

projectName

The name of the project that contains this procedure. The name must be unique among all projects.

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

Positional arguments

projectName, procedureName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteProcedure(<projectName>, <procedureName>);

Example

$ec->deleteProcedure("Default", "Take Snapshot");▼

ectool

syntax: ectool deleteProcedure <projectName> <procedureName>

Example

ectool deleteProcedure "Default" "Take Snapshot"▼

Back to top

deleteStep

Deletes a step from a procedure.

You must specify projectName, procedureName, and stepName.

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String
stepName	The name of the step that must be unique within the procedure. Argument type: String

Arguments

Descriptions

projectName

The name of the project that contains this procedure. The name must be unique among all projects.

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

stepName

The name of the step that must be unique within the procedure.

Argument type: String

Positional arguments

projectName, procedureName, stepName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteStep(<projectName>, <procedureName>, <stepName>);

Example

$ec->deleteStep("Default", "Run Build", "Compile");▼

ectool

syntax: ectool deleteStep <projectName> <procedureName> <stepName>

Example

ectool deleteStep "Default" "Run Build" "Compile"▼

Back to top

getProcedure

Finds a procedure by its name.

You must specify a projectName and a procedureName.

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String

Arguments

Descriptions

projectName

The name of the project that contains this procedure. The name must be unique among all projects.

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

Positional arguments

projectName, procedureName

Response

One procedure element, which includes the procedure ID, name, time created, job name template, owner, resource name, workspace name, project name, and so on.

ec-perl

syntax: $<object>->getProcedure(<projectName>, <procedureName>);

Example

$ec->getProcedure("Default", "Run Full Build");▼

ectool

syntax: ectool getProcedure <projectName> <procedureName>

Example

ectool getProcedure "Default" "Run Full Build"▼

Back to top

getProcedures

Retrieves all procedures in a project.

You must specify the projectName.

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. Argument type: String

Arguments

Descriptions

projectName

The name of the project that contains this procedure. The name must be unique among all projects.

Argument type: String

Positional arguments

projectName

Response

One or more procedure elements.

ec-perl

syntax: $<object>->getProcedures(<projectName>);

Example

$ec->getProcedures("Quarterly Summary");▼

ectool

syntax: ectool getProcedures <projectName>

Example

ectool getProcedures "Quarterly Summary"▼

Back to top

getStep

Retrieves a step from a procedure.

You must specify projectName, procedureName, and stepName.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String
stepName	The name of the step that must be unique within the procedure. Argument type: String

Arguments

Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

stepName

The name of the step that must be unique within the procedure.

Argument type: String

Positional arguments

projectName, procedureName, stepName

Response

One step element.

ec-perl

syntax: $<object>->getStep(<projectName>, <procedureName>, <stepName>);

Example

$ec->getStep("Default", "Run Build", "Compile");▼

ectool

syntax: ectool getStep <projectName> <procedureName> <stepName>

Example

ectool getStep "Default" "Run Build" "Compile"▼

Back to top

getSteps

Retrieves all steps in a procedure.

You must specify the projectName and procedureName.

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument type: String
procedureName	The name of the procedure that must be unique within the project. Argument type: String

Arguments

Descriptions

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

procedureName

The name of the procedure that must be unique within the project.

Argument type: String

Positional arguments

projectName, procedureName

Response

Zero or more step elements.

ec-perl

syntax: $<object>->getSteps(<projectName>, <procedureName>);

Example

$ec->getSteps("Default", "Run Build");▼

ectool

syntax: ectool getSteps <projectName> <procedureName>

Example

ectool getSteps "Default" "Run Build"▼

Back to top

modifyProcedure

Modifies an existing procedure.

You must specify projectName and procedureName.

Arguments Descriptions

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. You must also enter `procedureName`. Argument type: String
procedureName	The name of the procedure that must be unique within the project. You must also enter `projectName`. Argument type: String
credentialName	(Optional) Name of the credential in one of these forms: Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object. Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project. Argument type: String
description	(Optional) A plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. The only HTML tags allowed in the text are: `<a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>` Argument type: String
jobNameTemplate	(Optional) Job name format for jobs created by running this procedure. Argument type: String
newName	(Optional) New name of the procedure. Argument type: String
resourceName	(Optional) The name of the default resource where steps belonging to this procedure will run. This name can be a resource pool name. Argument type: String
timeLimit	(Optional) If no time limit was specified on the calling step, time limits are copied to the calling step from the procedure. If the procedure is called from `runProcedure` (or a schedule), the time limit acts as a global job timeout. The "timer" for the procedure starts as soon as the calling step/job becomes runnable (all preconditions are satisfied). Argument type: String
timeLimitUnits	(Optional) Time limit units are `hours\|minutes\|seconds`. Argument type: TimeLimitUnits
workspaceName	(Optional) The name of the default workspace where job output is stored. Argument type: String

projectName

The name of the project that contains this procedure. The name must be unique among all projects. You must also enter procedureName.

Argument type: String

procedureName

The name of the procedure that must be unique within the project. You must also enter projectName.

Argument type: String

credentialName

(Optional) Name of the credential in one of these forms:

Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.
Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

description

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

Argument type: String

jobNameTemplate

(Optional) Job name format for jobs created by running this procedure.

Argument type: String

newName

(Optional) New name of the procedure.

Argument type: String

resourceName

(Optional) The name of the default resource where steps belonging to this procedure will run. This name can be a resource pool name.

Argument type: String

timeLimit

(Optional) If no time limit was specified on the calling step, time limits are copied to the calling step from the procedure. If the procedure is called from runProcedure (or a schedule), the time limit acts as a global job timeout. The "timer" for the procedure starts as soon as the calling step/job becomes runnable (all preconditions are satisfied).

Argument type: String

timeLimitUnits

(Optional) Time limit units are hours|minutes|seconds.

Argument type: TimeLimitUnits

workspaceName

(Optional) The name of the default workspace where job output is stored.

Argument type: String

Positional arguments

projectName, procedureName

Response

Returns a modified procedure object.

ec-perl

syntax: $<object>->modifyProcedure(<projectName>, <procedureName>, {<optionals>});

Example

$ec->modifyProcedure("Test Proj", "Run Build", {resourceName =>
   "Windows—Bldg. 11"});▼

ectool

syntax: ectool modifyProcedure <projectName> <procedureName> [optionals]

Example

ectool modifyProcedure "Test Proj" "Run Build" --resourceName "Windows—Bldg. 11"▼

Back to top

modifyStep

Modifies an existing step.

You must specify projectName, procedureName, and stepName.

Arguments Descriptions

projectName

include::partial$name-for-the-project.adoc[] You must also enter the procedureName.

Argument type: String

procedureName

The name of the procedure that must be unique within the project. You must also enter projectName.

Argument type: String

stepName

The name of the step that must be unique within the procedure. You must also enter projectName and procedureName.

Argument type: String

actualParameter

(Optional) Specifies the values to pass as parameters to the called procedure. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the called procedure.

Argument type: Map

afterProcedureStep

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

Argument type: String

alwaysRun

(Optional) < Boolean flag - 0|1|true|false >

If set to 1 or true, this step will run even if the job is aborted before the step completes. This is a useful argument for running a "cleanup" step that should run whether the job is successful or not.

Argument type: Boolean

beforeProcedureStep

(Optional) The procedure step will be placed before the named procedure step if this option is used.

Argument type: String

broadcast

(Optional) < Boolean flag - 0|1|true|false > Use this flag to run the same step on several resources at the same time. The step is "broadcast" to all resources listed in the resourceName.

Argument type: Boolean

clearActualParameters

(Optional) < Boolean flag - 0|1|true|false >

If set to true or 1, all the actual parameters will be removed from the step.

Argument type: Boolean

command

(Optional) The step command.

Argument type: String

commandFile

(Optional) The contents of the command file is read and stored in the "command" field. This is an alternative argument for command and is useful if the "command" field spans multiple lines.

This option is supported only in Perl and ectool bindings—it is not part of the XML protocol.

comment

(Optional) The script to execute the functions of this step, which are passed to the step’s shell for execution.

Argument type: String

condition

(Optional) If empty or non-zero, the step will run. If set to "0", the step is skipped. A useful setting during procedure development or when re-running a job that has already completed some of the steps. Also, this argument is useful for conditional execution of steps based on properties set by earlier steps.

Argument type: String

credentialName

(Optional) Name of the credential in one of these forms:

Relative (for example, "cred1" )—The credential is assumed to be in the project that contains the request target object.
Absolute (for example, "/projects/BuildProject/credentials/cred1" )—The credential can be from any specified project, regardless of the target object’s project.

Argument type: String

description

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

Argument type: String

errorHandling

(Optional) Determines what happens to the procedure if the step fails: 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.

Argument type: ErrorHandling

exclusive

(Optional) < Boolean flag - 0|1|true|false >.

If set to 1 or true, this indicates this step should acquire and retain this resource exclusively. The default is 0 or false.

When you set exclusive, exclusiveMode is set to job.

Argument type: Boolean

exclusiveMode

(Optional) Use 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.

Argument type: ExclusiveMode

logFileName

(Optional) A custom log file name produced by running the step. By default, CloudBees Flow assigns a unique name to this file.

Argument type: String

newName

(Optional) New name of the step.

Argument type: String

parallel

(Optional) < Boolean flag — 0|1|true|false >

If this argument is set to 1 or true, this step and all adjacent steps marked with the flag set will run at the same time.

Argument type: String

postProcessor

(Optional) This command runs in parallel with the main command for the step. It analyzes the log for the step and collects diagnostic information.

Argument type: String

precondition

(Optional) By default, if the step has no precondition, it 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 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.

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 ( /myJob/buildInstallerCompleted=1 ).
Set a precondition in step 4: $[/myJob/buildInstallerCompleted]

Argument type: String

postProcessor

(Optional) The name of a program to run (script) after a step completes. This program looks at the step output to find errors and warnings. CloudBees Flow includes a customizable program called "postp" for this purpose.

Argument type: String

releaseExclusive

(Optional) < Boolean flag— 0|1|true|false >

This declares whether or not this step will release its resource, which is currently held exclusively. Setting this flag to 1 or true is the same as setting releaseMode to "release".

Argument type: Boolean

releaseMode

(Optional) Use 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.

Argument type: ReleaseMode

resourceName

(Optional) The name of the resource used by this step. It must be unique among all resources.

Argument type: String

shell

(Optional) Where shell is the name of a program used to execute commands contained in the "command" field. The name of a temporary file containing commands will be appended to the end of this invocation line. Normally, this file is a command shell, but it could be any other command line program. The default is to use the standard shell for the platform it runs on.

Argument type: String

subprocedure

(Optional) The name of the nested procedure to call when this step runs. If a subprocedure is specified, do not include the command or commandField.

Argument type: String

subproject

(Optional) If a subprocedure argument is used, this is the name of the project where that subprocedure is found. By default, the current project is used.

Argument type: String

timeLimit

(Optional) The maximum length of time the step is allowed to run. After the time specified, the step will be aborted.

Argument type: String

timeLimitUnits

(Optional) Units for step time limit: <hours|minutes|seconds>

Argument type: TimeLimitUnits

workingDirectory

(Optional) The CloudBees Flow agent sets this directory as the "current working directory," running the command contained in the step. If no working directory is specified in the step, CloudBees Flow uses the directory it created for the job in the CloudBees Flow workspace.

Argument type: String

workspaceName

(Optional) The name of the workspace used by this step.

Argument type: String

Positional arguments

projectName, procedureName, stepName

Response

None or a status OK message.

ec-perl

syntax: $<object>->modifyStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

Example

$ec->modifyStep("Default", "Run Build", "Compile", {commandFile => "tempfile.txt"});▼

ectool

syntax: ectool modifyStep <projectName> <procedureName> <stepName> [optionals]

Example

ectool modifyStep "Default" "Run Build" "Compile" --commandFile tempfile.txt▼

Back to top

moveStep

Moves a step within a procedure.

You must specify projectName, procedureName, and stepName.

Arguments Descriptions

Arguments	Descriptions
projectName	The name of the project that contains this procedure. The name must be unique among all projects. You must also enter `procedureName`. Argument type: String
procedureName	The name of the procedure that must be unique within the project. You must also enter `projectName`. Argument type: String
stepName	The name of the step that must be unique within the procedure. You must also enter `projectName` and `procedureName`. Argument type: String
beforeStep	(Optional) Moves the step ( `stepName` ) to position before the step "named" by this option. If omitted, `stepName` is moved to the end of the list of steps. Argument type: String

projectName

The name of the project that contains this procedure. The name must be unique among all projects. You must also enter procedureName.

Argument type: String

procedureName

The name of the procedure that must be unique within the project. You must also enter projectName.

Argument type: String

stepName

The name of the step that must be unique within the procedure. You must also enter projectName and procedureName.

Argument type: String

beforeStep

(Optional) Moves the step ( stepName ) to position before the step "named" by this option. If omitted, stepName is moved to the end of the list of steps.

Argument type: String

Positional arguments

projectName, procedureName, stepName

Response

None or a status OK message.

ec-perl

syntax: $<object>->moveStep(<projectName>, <procedureName>, <stepName>, {<optionals>});

Example

$ec->moveStep("Default", "Run Build", "Get Sources", {beforeStep => "Compile"});▼

ectool

syntax: ectool moveStep <projectName> <procedureName> <stepName> [optionals]

Example

ectool moveStep "Default" "Run Build" "Get Sources" --beforeStep "Compile"▼

Back to top