Pipelines and Releases

abortAllPipelineRuns

Aborts all pipeline runs associated with a release.

Arguments Descriptions

force

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the pipelines abort immediately. A zero value allows the running tasks in the pipeline stage to terminate.

Argument Type: Boolean

pipelineName

(Optional) Name of the pipeline.

Argument Type: String

projectName

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

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName

Response

None or a status OK message.

ec-perl

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

Example

$ec->abortAllPipelineRuns("Production", {force => true, pipelineName => "banking"});

ectool

syntax: ectool abortAllPipelineRuns <projectName> [optionals]

Example

ectool abortAllPipelineRuns "Production" --force true --pipelineName "banking"

abortPipelineRun

Aborts a pipeline run.

Arguments Descriptions

flowRuntimeId

(Optional) The ID of the flow runtime.

Argument Type: UUID

flowRuntimeName

(Optional) The name of the flow runtime.

Argument Type: String

force

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the pipeline aborts immediately. A zero value allows the running task in the pipeline stage to terminate.

Argument Type: Boolean

projectName

(Optional) The name of the project.

Argument Type: String

Positional arguments

None

Response

None or a status OK message.

ec-perl

syntax: $<object>->abortPipelineRun( {<optionals>});

Example

$ec->abortPipelineRun({flowRuntimeName => "Final Release", projectName => "Production"});

ectool

syntax: ectool abortPipelineRun [optionals]

Example

ectool abortPipelineRun --flowRuntimeName "Final Release" --projectName "Production"

attachPipelineRun

Add a pipeline run to a release with status running or planning ; pipeline runs cannot be attached to completed releases. All arguments are required.

Arguments Descriptions

projectName

The name of the project in which the pipeline and release reside.

Argument Type: String

flowRuntimeId

The ID of the flow runtime representing the pipeline run to attach. Only top level pipeline runs are eligible to be attached. Release runs or triggered pipeline runs are ineligible.

Argument Type: UUID

releaseName

Name of the release to attach the pipeline run. The release must be in planning or running state; pipeline runs cannot be attached to completed pipelines.

Argument Type: String

Positional arguments

projectName

Response

None or a status OK message.

ec-perl

syntax: $<object>->attachPipelineRun (<project_name>, flowRuntimeId ⇒ <flow_runtime_id>, releaseName ⇒ <release_name>);

Example

$ec->attachPipelineRun("Default", flowRuntimeId => e9bebbe3-c087-11e9-8bf5-001c42c3ce23, releaseName => AugustRelease);

ectool

syntax: ectool attachPipelineRun <project_name> --flowRuntimeId <flow_runtime_id> --releaseName <release_name>

Example

ectool attachPipelineRun "Default" --flowRuntimeId e9bebbe3-c087-11e9-8bf5-001c42c3ce23 --releaseName "AugustRelease"

completeManualTask

Completes the manual task.

You must specify the flowRuntimeId, stageName, and taskName arguments.

Arguments Descriptions

flowRuntimeId

ID of the flow runtime.

Argument Type: UUID

stageName

Name of the stage.

Argument Type: String

taskName

Name of the task.

Argument Type: String

action

(For manual tasks and approval gate rules) The type of action to be taken on the pipeline stage manual task or gate rule. Valid values are completed and failed. Additionally, skip is an available value if this manual task or gate rule is configured with ` allowSkip=true`.

If this task is configured with disableFailure=1, then this argument is ignored—the task always completes with success.

Note: if action=skip is supplied, then parameters supplied with the actualParameters argument are ignored.

Argument type: ManualProcessStepStatus

actualParameters

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

Note: if action=skip is supplied, then parameters supplied with the actualParameters argument are ignored.

Argument Type: Map

evidence

(Optional) User-supplied evidence provided while performing an action on the pipeline stage manual task or stage gate task.

Argument type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument type: GateType

Positional arguments

flowRuntimeId, stageName, taskName

Response

None or a status OK message.

ec-perl

syntax: $<object>->completeManualTask(<flowRuntimeId>, <stageName>, <taskName>, {<optionals>});

Example

$ec->completeManualTask("4fa765dd-73f1-11e3-b67e-b0a420524153", "Final Deploy", "Confirm version"});

ectool

syntax: ectool completeManualTask <flowRuntimeId> <stageName> <taskName> [optionals]

Example

ectool completeManualTask 4fa765dd-73f1-11e3-b67e-b0a420524153 "Final Deploy" "Confirm version"

completeRelease

Completes the Release.

Arguments Descriptions

projectName

(Optional) The name of the project.

Argument Type: Map

releaseId

(Optional) The release ID.

Argument Type: UUID

releaseName

(Optional) Name of the release.

Argument Type: String

Response

None or a status OK message.

ec-perl

syntax: $<object>->completeRelease( {<optionals>});

Example

$ec->completeRelease({projectName => "Production", releaseName => "Final"});

ectool

syntax: ectool completeRelease [optionals]

Example

ectool completeRelease --projectName "Production" --releaseName "Final"

createDeployer

Creates a new Deployer task for a project or a Release.

You must specify the projectName and the deployerName.

Arguments Descriptions

projectName

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

Argument Type: String

Argument Type: String

deployerName

The name of the Deployer task that must be unique within the project.

Argument Type: String

Positional arguments

projectName, deployerName

Response

Returns a Deployer object.

ec-perl

syntax: $<object>->createDeployer(<projectName>, <deployerName>);

Example

$ec->createDeployer("Default", "Deploy Shopping Cart");

ectool

syntax: ectool createDeployer <projectName> <deployerName>

Example

ectool createDeployer "Default" "Deploy Shopping Cart"

createDeployerApplication

Adds a Deployer application to a Release.

You must specify the projectName and applicationName arguments.

Arguments Descriptions

projectName

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

Argument Type: String

Argument Type: String

applicationName

The name of the application.

Argument Type: String

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the Release project name.

Argument Type: String

errorHandling

(Optional) The error handling method for the Deployer application.

Argument Type: FlowStateErrorHandling

orderIndex

(Optional) The order in which the applications are deployed, starting from 1.

Argument Type: String

processName

(Optional) The name of the application process.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

smartDeploy

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the pipeline uses smart deploy when the application is deployed. immediately. CloudBees CD deploys the application only with artifacts that have not been deployed to a resource or with selected versions of the artifact have not been deployed to new resources since a previous run.

When this argument is set to false or 0, the pipeline deploys all the application processes, components, and artifacts in the application, referred to as a full run .

Argument Type: Boolean

snapshotName

(Optional) The name of the application snapshot.

Argument Type: String

stageArtifacts

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, artifact staging is enabled for the application process. CloudBees CD retrieves artifacts that will be deployed in an application run before the deployment starts.

When this argument is set to false or 0, artifact staging is disabled.

Argument Type: Boolean

Positional arguments

projectName, applicationName

Response

Returns a Deployer application object.

ec-perl

syntax: $<object>->createDeployerApplication(<projectName>, <applicationName>, {<optionals>});

Example

$ec->createDeployerApplication("Default", "Shopping Cart", {applicationProjectName => "Deploy cart"});

ectool

syntax: ectool createDeployerApplication <projectName> <applicationName> [optionals]

Example

ectool createDeployerApplication "Default" "Shopping Cart" --applicationProjectName "Deploy cart"

createDeployerConfiguration

Adds the Deployer configuration to the Deployer application.

You must specify the projectName, applicationName, and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

stageName

Name of the stage in the pipeline. If a Release is also specified, the pipeline is defined in the Release.

Argument Type: String

actualParameters

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

Argument Type: Map

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the Release project name.

Argument Type: String

environmentName

(Optional) Name of the environment.

Argument Type: String

environmentProjectName

(Optional) Name of the project containing the specified environment or environment template. If this argument is not specified, the default is the Release project name.

Argument Type: String

environmentTemplateName

(Optional) Name of the environment template.

Argument Type: String

environmentTemplateProjectName

(Optional) Name of the project containing specified environment template. If this argument is not specified, the default is the environment project name.

Argument Type: String

insertRollingDeployManualStep

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 a manual step needs to be added after each phase or batch is run.

Argument type: Boolean

releaseName

(Optional) Name of the release.

Argument Type: String

rollingDeployEnabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 the pipeline runs the rolling deployment.

Argument type: Boolean

rollingDeployManualStepAssignees

(Optional) A list of assignees who receive the notification when the rolling deploy iteration is completed.

Argument type: Collection

rollingDeployManualStepCondition

(Optional) The Run if condition (run condition) on the manual step that was created during the rolling deployment.

Argument type: NotificationType

rollingDeployPhases

(Optional) One or more rolling deploy phases to be used in the rolling deployment.

Argument type: Collection

serviceName

(Optional) Name of the service.

Argument type: String

skipDeploy

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the application is not deployed to an environment.

Argument type: Boolean

Positional arguments

projectName, applicationName, stageName

Response

Returns a Deployer configuration object.

ec-perl

syntax: $<object>->createDeployerConfiguration(<projectName>, <applicationName>, <stageName>,{<optionals>});

Example

$ec->createDeployerConfiguration("Default", "Shopping Cart", "PROD", {releaseName => "Q1 Summary"});

ectool

syntax: ectool createDeployerConfiguration <projectName> <applicationName> <stageName> [optionals]

Example

ectool createDeployerConfiguration "Default" "Shopping Cart" "PROD" --releaseName "Q1 Summary"

createDeployerService

Adds a Deployer service to the specified release.

You must specify the projectName and serviceName arguments.

Arguments Descriptions

projectName

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

Argument Type: String

Argument Type: String

serviceName

The name of the service Argument.

Type: String

afterLastRetry

(Optional) Specify continue or stop pipeline execution after last unsuccessful retry or a task.

Argument Type: AfterLastRetryErrorHandling

enforceDependencies

(Optional) Enforce dependencies flag to be used during runProcess for the application.

Argument Type: Boolean

errorHandling

(Optional) Specifies error handling for the deployer application.

Argument Type: FlowStateErrorHandling

orderIndex

(Optional) Specifies the application deployment order (starts from 1).

Argument Type: Integer

processName

(Optional) The name of the application process.

Argument Type: String

releaseName

(Optional) The name of the release.

Argument Type: String

retryApprovers

(Optional) A list of retry approvers who receive the notification.

Argument Type: Collection

retryCount

(Optional) If the retry is auto, specify the maximum number of times retry should occur.

Argument Type: String

retryInterval

(Optional) If the retry is auto, specify the number of seconds to wait until the next retry should occur.

Argument Type: String

retryNotificationTemplate

(Optional) Email retry notification template for application.

Argument Type: String

retryType

(Optional) Type of retry when process step or task fails. Is one of 'auto' or 'manual'.

Argument Type: RetryType

serviceProjectName

(Optional) The name of the project containing specified service. If not specified, it is defaulted to the release project name.

Argument Type: String

snapshotName

(Optional) The name of the snapshot.

Argument Type: String

Positional arguments

projectName, serviceName

Response

Returns a Deployer microservice object.

ec-perl

syntax: $<object>->createDeployerService(<projectName>, <serviceName>, {<optionals>});

Example

$ec->createDeployerService("Default", "Shopping Cart", {serviceProjectName => "Deploy cart"});

ectool

syntax: ectool createDeployerService<projectName> <serviceName> [optionals]

Example

ectool createDeployerService"Default" "Shopping Cart" --serviceProjectName "Deploy cart"

createGate

Creates a new gate for a stage.

You must specify the projectName, stageName, and gateType.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

gateType

Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing the next stage. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. An \"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)]

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

precondition

(Optional) A property that allows the stage to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition) is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName, stageName, gateType

Response

Returns a pipeline gate object.

ec-perl

syntax: $<object>->createGate(<projectName>, <stageName>, <gateType>, {<optionals>});

Example

$ec->createGate("Default", "Preflight", POST, {pipelineName => "Quarterly Summary"});

ectool

syntax: ectool createGate <projectName> <stageName> <gateType> [optionals]

Example

ectool createGate "Default" "Preflight" POST --pipelineName "Quarterly Summary"

createNote

Creates a new note.

You must specify note.

Arguments Descriptions

note

Notes about the entity.

Argument Type: String

noteName

(Optional) Name of the note.

Argument Type: String

projectName

(Optional) Project name of the entity that owns the note.

Argument Type: String

releaseName

(Optional) Name of the release that references the pipeline.

Argument Type: String

Positional arguments

note

Response

Returns a Deployer application object.

ec-perl

syntax: $<object>->createNote(<note>, {<optionals>});

Example

$ec->createNote("Approved by ABC", {releaseName => "Production"});

ectool

syntax: ectool createNote <note> [optionals]

Example

ectool createNote "Approved by ABC" --releaseName "Production"

createPipeline

Creates a new pipeline for a project.

You must specify the projectName and pipelineName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

Name of the pipeline that must be unique among all projects.

Argument Type: String

assigneesForSkipStage

(Optional) A list of users who can skip stages at runtime.

Argument Type: Collection

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

disableMultipleActiveRuns

(Optional) Control whether more than one active run is allowed for this pipeline.

If true or 1, disable ability to have more than one active run for this pipeline.

If false or 0, enable ability to have more than one active run for this pipeline. (default)

Argument Type: Boolean

disableRestart

(Optional) Control whether pipeline can be restarted.

If true or 1, disable ability to restart pipeline.

If false or 0, enable ability to restart pipeline. (default)

Argument Type: Boolean

enabled

(Optional) Control whether pipeline is enabled.

If true or 1, the pipeline is enabled. (default)

Argument type: Boolean

overrideWorkspace

(Optional) Control whether tasks use pipeline’s workspace

If true or 1, and workspaceName is not NULL, then all tasks use this pipeline’s workspace.

If If false or 0, tasks use original workspace. (default)

Argument type: Boolean

pipelineRunNameTemplate

(Optional) Template for the pipeline run name. If not specified, the pipeline run name is constructed from pipelineName.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

skipStageMode

(Optional) The flag to indicate if stages can be skipped at runtime.

Argument Type: StageSkipMode

type

(Optional) Type of pipeline.

Argument Type: PipelineType

workspaceName

(Optional) The name of the workspace.

Argument Type: String

Positional arguments

projectName, pipelineName

Response

Returns a pipeline object.

ec-perl

syntax: $<object>->createPipeline(<projectName>, <pipelineName>, {<optionals>});

Example

$ec->createPipeline("Default", "Web Server Image", {description => "Amazon"});

ectool

syntax: ectool createPipeline <projectName> <pipelineName> [optionals]

Example

ectool createPipeline "Default" "Web Server Image" --description "Amazon"

createRelease

Creates a new release for a project. When the pipelineName and pipelineProjectName arguments are not provided, a new release-scoped pipeline is created under the new release. When the pipelineName and pipelineProjectName arguments are provided, then the pipeline is cloned to a new pipeline under the new release.

You must specify the projectName and the releaseName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

actualParameters

(Optional) Actual parameters.

Argument Type: Map

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

disableMultipleActiveRuns

(Optional) Control whether more than one active run is allowed for this release pipeline.

If true or 1, disable ability to have more than one active run for this release pipeline.

If false or 0, enable ability to have more than one active run for this release pipeline. (default)

Argument Type: Boolean

disablePipelineRestart

(Optional) Control whether pipeline can be restarted.

If true or 1, disable ability to restart pipeline.

If false or 0, enable ability to restart pipeline. (default)

Argument Type: Boolean

overrideWorkspace

(Optional) Control whether tasks use release pipeline’s workspace

If true or 1, and workspaceName is not NULL, then all tasks use this release pipeline’s workspace.

If If false or 0, tasks use original workspace. (default)

Argument type: Boolean

pipelineName

(Optional) Name of the pipeline. The pipeline is cloned to make it release-scoped.

Argument Type: String

pipelineProjectName

(Optional) The name of the project containing specified pipeline. If this argument is not specified, the default is the release project name.

Argument Type: String

pipelineWorkspaceName

(Optional) The name of the workspace.

Argument Type: String

plannedEndDate

(Optional) The date when this release is expected to end (for example, 2016-05-15).

Argument Type: String

plannedStartDate

(Optional) The date when this release is expected to begin (for example, 2016-05-15)

Argument Type: String

timeZone

(Optional) The time zone to use for this release. If not specified, the user’s time zone is used.

Argument Type: String

Positional arguments

projectName, releaseName

Response

Returns a release object.

ec-perl

syntax: $<object>->createRelease(<projectName>, <releaseName>, {<optionals>});

Example

$ec->createRelease("Default", "Production", {description => "Pet Shop Web Site", pipelineName => "Daily Update"});

ectool

syntax: ectool createRelease <projectName> <releaseName> [optionals]

Example

ectool createRelease "Default" "Production" --description "Pet Shop Web Site" --pipelineName "Daily Update"

createStage

Creates a new stage in a pipeline for a project.

You must specify the projectName and the stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

afterStage

(Optional) The stage that is placed after the new stage.

Argument Type: String

beforeStage

(Optional) The stage that is placed before the new stage.

Argument Type: String

colorCode

(Optional) The hexadecimal value of the color to be used with an entity.

Argument Type: String

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing the next stage. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. An \"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)]

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

precondition

(Optional) A property that allows the stage to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition) is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName, stageName

Response

Returns a pipeline stage object.

ec-perl

syntax: $<object>->createStage(<projectName>, <stageName>, {<optionals>});

Example

To specify that the Preflight stage run after the "Automated Tests" stage, enter:

$ec->createStage("Default", "Preflight", {afterStage => "Automated Tests"});

To set the Wait until condition (precondition) that the "Automated Tests" stage is completed before running the "Preflight" stage, enter:

$ec->createStage("Default", "Preflight", {precondition => "$[/myPipelineRuntime/autoTestCompleted]"});

To set the Run if condition (run condition) that the name of the next stage is "Preflight", enter:

$ec->createStage("Default", "Preflight", {condition => "$[/javascript (myPipelineRuntime.pipelineName == myPipelineRuntime.Preflight)]"});

ectool

syntax: ectool createStage <projectName> <stageName> [optionals]

Example

To specify that the Preflight stage run after the "Automated Tests" stage, enter:

ectool createStage "Default" "Preflight" --afterStage "Automated Test"

To set the Wait until condition (precondition) that the "Automated Tests" stage is completed before running the "Preflight" stage, enter:

ectool createStage "Default" "Preflight" --precondition "$[/myPipelineRuntime/autoTestCompleted]"

To set the Run if condition (run condition) that the name of the next stage is "Preflight", enter:

ectool createStage "Default" "Preflight" --condition "$[/javascript (myPipelineRuntime.pipelineName == myPipeline.Preflight)]"

createTask

Creates a new task for a task container.

You must specify the projectName and taskName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

taskName

Name of the task.

Argument Type: String

actionLabelText

The JSON string used to assign custom label text to manual task or approval gate rule actions.

{
   "completed":"",
   "failed":"",
   "skipped":""
}

Where:

  • completedLabel —used for successful outcome; default label for manual tasks is Completed, default label for approval gate rules is Approve.

  • failedLabel —used for unsuccessful outcome; default label for manual tasks is Failed, default label for approval gate rules is Reject.

  • skippedLabel —used for task skipping; default label for manual tasks is Skip this task, default label for approval gate rules is Skip this gate.

Argument Type: String

actualParameters

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

Argument Type: Map

advancedMode

(Optional) < Boolean flag0|1|true|false >

When advancedMode is set to true or 1, advanced mode is enabled so that all validations for the applicationName, environmentName, processName, or snapshotName will be skipped. These objects can be represented using the " $[] " notation and later expanded at the pipeline runtime. For example, when advancedMode is enabled, the system does not validate that the environment exists or whether it is mapped to an application.

Argument type: Boolean

afterLastRetry

(Optional) <continueOnError|stopOnError> ]

Specifies whether to continue or stop pipeline execution after the last unsuccessful retry of a task. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is stopOnError.

Argument Type: AfterLastRetryErrorHandling

afterTask

(Optional) The task that is placed after the named task.

Argument Type: String

allowOutOfOrderRun

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task can be run out of order.

Argument type: Boolean

allowSkip

(Optional) < Boolean flag0|1|true|false >(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task can be skipped at runtime—only users specified in the approver list will be allowed to skip. Available when taskType = {MANUAL, APPROVAL}.

Argument type: Boolean

alwaysRun

(Optional) true means this task will run even if preceding tasks fail in a way that abort the pipeline. This lets you define an "always run" task, which will run regardless of the error handling behavior for any preceding tasks. This facility is most commonly used for cleanup operations at the end of a stage or gate.

Argument Type: Boolean

approvers

(Optional) <approver1> <approver2> …​

A list of task approvers who receive the notification. Available when taskType = {MANUAL, APPROVAL} and for any other type of task if errorHandling for the task is set to retryOnError and retryType is set to manual.

Argument Type: Collection

beforeTask

(Optional) The task that is placed before the named task.

Argument Type: String

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing the next task. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. An \"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)]

Argument Type: String

ciConfigurationName

Name of the CI configuration containing the CI job of interest.

Must be specified when taskType = CI_JOB.

Argument Type: String

ciJobFolder

Path to the folder on the CI server referenced by ciConfigurationName that contains the specified CI job. Must be in format folder1/folder2/folder3/…​. Available when taskType = CI_JOB.

If not specified, root folder for on the CI server is used.

Argument Type: String

ciJobName

Name of the CI job to run for this task.

Must be specified when taskType = CI_JOB.

Argument Type: String

credentials

(Optional) The credentials for the task.

Argument type: Collection

deployerRunType

(Optional) <parallel|serial>

The type of deployer run for the deployer type of task. If you specify parallel, then all applications are deployed in parallel.

Argument Type: DeployerRunType

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

disableFailure

(Optional) < Boolean flag0|1|true|false >(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task cannot be failed—it will always complete with success. Available when taskType = MANUAL.

Argument type: Boolean

emailConfigName

(Optional) The name of email configuration.

Argument Type: String

enabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the task is enabled.

Argument type: Boolean

environmentName

(Optional) Name of the environment to create from a template.

When the environmentTemplateName is specified, the environmentName can be specified using the " $[] " notation. It is expanded at runtime.

Argument Type: String

environmentProjectName

(Optional) Name of the project to which the environment or environment template belongs.

Argument Type: String

environmentTemplateName

(Optional) Name of the environment template to use.

When the environmentTemplateName is specified, the environmentName can be specified using the " $[] " notation. It is expanded at runtime.

Argument Type: String

environmentTemplateProjectName

(Optional) Name of the project containing specified environment template. If this argument is not specified, the default is the environment project name.

Argument Type: String

errorHandling

(Optional) <continueOnError|retryOnError|stopOnError>

Type of error handling for this task. The default is stopOnError>.

Argument Type: FlowStateErrorHandling

firstTask

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, this task is the first task in the stage, and the beforeTask and afterTask arguments should not be used. The default is false or 0.

Argument type: Boolean

gateType

(Optional) Type of the gate. Valid values are PRE and POST. Use to specify that this task is a gate rule. If hot specified, this task is a stage task.

Argument Type: GateType

insertRollingDeployManualStep

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 a manual step needs to be added after each phase or batch is run.

Argument type: Boolean

instruction

(Optional) Instruction associated with the task.

Argument Type: String

keepOnError

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the system is set to keep environment if an error occurs. The default is false or 0.

Argument type: Boolean

notificationTemplate

(Optional) String containing email formatting instructions for generating notifications. This can be used only for APPROVAL and MANUAL types of task and for any other type of task that has errorHandling set to retryOnError and retryType set to manual.

Argument type: String

outOfOrderRunAssignees

(Optional) A list of one or more users who can run this task out of order. If not specified, all users can run the task out of order.

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

precondition

(Optional) A property that allows the task to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition) is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

Name of the release.

Argument Type: String

retryCount

(Optional) Specifies the maximum number of times that the retry should occur. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is 3.

Argument type: String

retryInterval

(Optional) Specifies the number of seconds to wait until the next retry. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is 60.

Argument type: String

retryType

(Optional) <auto|manual>

Specifies the type of retry when a process step or task fails. This can be used only for a task with errorHandling set to retryOnError. The default is auto.

Argument type: RetryType

skippable

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the task can be skipped in the pipeline. Not in use—use allowSkip instead.

Argument type: Boolean

rollingDeployEnabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 the pipeline runs the rolling deployment.

Argument type: Boolean

rollingDeployManualStepAssignees

(Optional) A list of assignees who receive the notification when the rolling deploy iteration is completed.

Argument type: Collection

rollingDeployManualStepCondition

(Optional) The Run if condition (run condition) on the manual step that was created during the rolling deployment.

Argument type: NotificationType

rollingDeployPhases

(Optional) One or more rolling deploy phases to be used in the rolling deployment.

Argument type: Collection

snapshotName

(Optional) Name of the snapshot associated with the application.

When advancedMode is set to true or 1, advanced mode is enabled so that all validations for the applicationName, environmentName, processName, or snapshotName will be skipped. These objects can be represented using the " $[] " notation and later expanded at the pipeline runtime. For example, when advancedMode is enabled, the system does not validate that the environment exists or whether it is mapped to an application.

Argument type: String

stageName

(Optional) Name of the stage to which the task belongs.

Argument Type: String

startTime

(Optional) The time to begin invoking this task.

The time is formatted hh:mm using the 24-hours clock (for example, 17:00).

Argument Type: String

subapplication

(Optional) Name of the application that owns the subprocess.

Argument Type: String

subpluginKey

(Optional) Name of the pluginKey for a procedure when the procedure is referenced.

Argument Type: String

subprocedure

(Optional) Name of the subprocedure when a procedure is referenced.

Argument Type: String

subprocess

(Optional) Name of the CloudBees CD process.

Argument Type: String

subproject

(Optional) Name of the project in which the procedure runs.

Argument Type: String

subworkflowDefinition

(Optional) Name of the workflow definition in which the workflow definition is referenced.

Argument Type: String

subworkflowStartingState

(Optional) Name of the starting state in the specified workflow definition.

Argument Type: String

taskProcessType

(Optional) The type of the process that the task can invoke.

Argument Type: TaskProcessType

taskType

(Optional) The type of the task. One of: [APPROVAL|CI_JOB|COMMAND|CONDITIONAL|DEPLOYER|GROUP|MANUAL|PIPELINE|PLUGIN|PROCEDURE|PROCESS|RELEASE|UTILITY|WORKFLOW].

Argument Type: TaskType

tierResourceCounts

(Optional) The resource count per resource template tier.

Argument Type: Map

useApproverAcl

(Optional) < Boolean flag0|1|true|false >

Used for manual stage tasks (see ). When this argument is set to true or 1, use approver’s permissions for further pipeline execution.

Argument type: Boolean

workspaceName

(Optional) The name of the workspace.

Argument Type: String

Positional arguments

projectName, taskName

Response

Returns a task object.

ec-perl

syntax: $<object>->createTask(<projectName>, <taskName>, {<optionals>});

Example

To run the "Save results" task before the "Save log file" task:

$ec->createTask("Default", "Save results", {beforeTask => "Save log file"});

To create a task as the first task in a stage:

$ec->createTask("Default", "Enter user name and password", {firstTask => true});

To create a task with Run if and Wait until conditions:

$ec->createTask("Default", "Deploy WAR file", {condition => $[/javascript (myTask.taskName == myTask.deployWar), precondition => $[/myTask/autoTestCompleted]]});

To create a task and assign user-defined labels to the actions:

$ec->createTask( "proj", "task4", {stageName => 'Stage 1', pipelineName => pipe1, actionLabelText => '{"completed":"Approve","failed":"Reject","skipped":"Skip"}', --taskType => MANUAL});

To create a gate rule and assign user-defined labels to the actions:

$ec->createTask( "proj", "rule3", {stageName => 'Stage 1', pipelineName => pipe1, gateType => PRE actionLabelText => '{"completed":"Approve","failed":"Reject","skipped":"Skip"}', --taskType => APPROVAL});

ectool

syntax: ectool createTask <projectName> <taskName> [optionals]

Example

To run the "Save results" task before the "Save log file" task:

ectool createTask "Default" "Save results" --beforeTask "Save log file"

To create a task as the first task in a stage:

ectool createTask "Default" "Enter user name and password" --firstTask true

To create a task with Run if and Wait until conditions:

ectool createTask "Default" "Deploy WAR file" --condition "$[/javascript (myTask.taskName == myTask.deployWar)" --precondition "$[/myTask/autoTestCompleted]"

To create a task and assign user-defined labels to the actions:

ectool createTask proj task4 --stageName 'Stage 1' --pipelineName pipe1 --actionLabelText '{"completed":"Approve","failed":"Reject","skipped":"Skip"}' --taskType MANUAL

To create a gate rule and assign user-defined labels to the actions:

ectool createTask proj rule3 --stageName 'Stage 1' --pipelineName pipe1 --gateType PRE --actionLabelText '{"completed":"Approve","failed":"Reject","skipped":"Skip"}' --taskType APPROVAL

createTaskGroup

Modifies tasks in a stage or a gate to create a group of parallel tasks or adds them to an existing group. The default error handling for group tasks is stopOnError>.

You must specify the projectName argument.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

groupName

(Optional) Name of the group task.

Argument Type: String

groupRunType

(Optional) Type of the subtask run for a group task. Valid values are parallel and serial. If serial, then all tasks are run in serial; otherwise in parallel (by default).

Argument Type: TaskRunType

pipelineName

(Optional) Name of the pipeline.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

stageName

(Optional) Name of the stage to which this task belongs.

Argument Type: String

taskNames

(Optional) Tasks to put into the group.

Argument Type: Collection

Positional arguments

projectName

Response

Returns a group of parallel tasks.

ec-perl

syntax: $<object>->createTaskGroup(<projectName> {<optionals>});

Example

$ec->createTaskGroup("Default", {groupName => "Group3", pipelineName => "Heatclinic pipeline DSL",  stageName => "QA", taskName => [ "Undeploy HeatClinic from Static Environment", "Deploy HeatClinic on Static Environment"]});

ectool

syntax: ectool createTaskGroup <projectName> [optionals]

Example

./ectool createTaskGroup "Default" --groupName "Group3" --pipelineName "Heatclinic pipeline DSL" --stageName "DEV" --taskNames "Undeploy HeatClinic from Static Environment" "Deploy HeatClinic on Static Environment"

deleteGate

Deletes a gate in a stage.

You must specify the projectName, stageName, and gateType.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

gateType

Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, stageName, gateType

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteGate(<projectName>, <stageName>, <gateType>, {<optionals>});

Example

$ec->deleteGate("Default", "Preflight", POST, {pipelineName => "Quarterly Summary"});

ectool

syntax: ectool deleteGate <projectName> <stageName> <gateType> [optionals]

Example

ectool deleteGate "Default" "Preflight" POST --pipelineName "Quarterly Summary"

deleteNote

Deletes a note associated with an entity.

You must specify note.

Arguments Descriptions

note

Notes provided about the entity.

Argument Type: String

projectName

(Optional) Project name of the entity that owns the note.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

note

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteNote(<note>, {<optionals>});

Example

$ec->deleteNote("Approved by ABC", {releaseName => "Production"});

ectool

syntax: ectool deleteNote <note> [optionals]

Example

ectool deleteNote "Approved by ABC" --releaseName "Production"

deletePipeline

Deletes a pipeline in a project.

You must specify the projectName and the pipelineName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

Name of the pipeline that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, pipelineName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deletePipeline(<projectName>, <pipelineName>);

Example

$ec->deletePipeline("Default", "Web Server Image");

ectool

syntax: ectool deletePipeline <projectName> <pipelineName>

Example

ectool deletePipeline "Default" "Web Server Image"

deletePipelineRun

Deletes a pipeline runtime.

Arguments Descriptions

flowRuntimeId

(Optional) The ID of the flow runtime.

Argument Type: UUID

flowRuntimeName

(Optional) The name of the flow runtime.

Argument Type: String

projectName

(Optional) The name of the project.

Argument Type: String

Response

None or a status OK message.

ec-perl

syntax: $<object>->deletePipelineRun({<optionals>});

Example

$ec->deletePipelineRun({flowRuntimeName => "Test Run", projectName => "Default"});

ectool

syntax: ectool deletePipelineRun [optionals]

Example

ectool deletePipelineRun --flowRuntimeName "Test Run" --projectName "Default"

deleteRelease

Deletes a Release.

You must specify the projectName and releaseName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, releaseName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteRelease(<projectName>, <releaseName>);

Example

$ec->deleteRelease("Default", "Pet Store");

ectool

syntax: ectool deleteRelease <projectName> <releaseName>

Example

ectool deleteRelease "Default" "Pet Store"

deleteStage

Deletes a stage in a project.

You must specify the projectName and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, stageName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteStage(<projectName>, <stageName>, {<optionals>});

Example

$ec->deleteStage("Default", "PROD", {pipelineName => "Q2 Summary"});

ectool

syntax: ectool deleteStage <projectName> <stageName> [optionals]

Example

ectool deleteStage "Default" "PROD" --pipelineName "Q2 Summary"

deleteTask

Deletes a task in a task container.

You must specify the projectName and taskName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

taskName

Name of the task.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

releaseName

Name of the release.

Argument Type: String

stageName

(Optional) Name of the stage to which the task belongs.

Argument Type: String

Positional arguments

projectName, taskName

Response

None or a status OK message.

ec-perl

syntax: $<object>->deleteTask(<projectName>, <taskName>, {<optionals>});

Example

$ec->deleteTask("Default", "Save image", {pipelineName => "Production"});

ectool

syntax: ectool deleteTask <projectName> <taskName> [optionals]

Example

ectool deleteTask "Default" "Save image" --pipelineName "Production"

detachPipelineRun

Detach a pipeline run from the specified release. All arguments are required.

Arguments Descriptions

projectName

The name of the project in which the pipeline and release reside.

Argument Type: String

flowRuntimeId

The ID of the flow runtime representing the pipeline run to detach. Only top level pipeline runs are eligible to be attached. Release runs or triggered pipeline runs are ineligible.

Argument Type: UUID

releaseName

Name of the release from which to detach the flow runtime. Pipeline runs cannot be detached from completed releases.

Argument Type: String

Positional arguments

projectName

Response

None or a status OK message.

ec-perl

syntax: $<object>->detachPipelineRun (<project_name>, flowRuntimeId ⇒ <flow_runtime_id>, releaseName ⇒ <release_name>);

Example

$ec->detachPipelineRun("Default", flowRuntimeId => e9bebbe3-c087-11e9-8bf5-001c42c3ce23, releaseName => AugustRelease);

ectool

syntax: ectool detachPipelineRun <project_name> --flowRuntimeId <flow_runtime_id> --releaseName <release_name>

Example

ectool detachPipelineRun "Default" --flowRuntimeId e9bebbe3-c087-11e9-8bf5-001c42c3ce23 --releaseName "AugustRelease"

getAllWaitingTasks

Retrieves a list of all tasks across pipeline runs that are awaiting manual approval.

Arguments Descriptions

Get waiting tasks for all active runs for the specified release.

projectName

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

Argument type: String

releaseName

Name of the release.

Argument type: String

Get waiting tasks for the specific flow runtime.

flowRuntimeId

Get all waiting tasks from all stages in the pipeline run, including pre-run tasks, specified by flowRuntimeId.

Positional arguments

None.

Response

Returns all waiting task objects across pipeline runs that are awaiting manual approval.

ec-perl

syntax:

$<object>->getAllWaitingTasks(<projectName>, <releaseName>);

$<object>->getAllWaitingTasks(<flowRuntimeId>);

Example

$ec->getAllWaitingTasks(projectName -> "proj1", {releaseName => "release1"});
$ec->getAllWaitingTasks(flowRuntimeId -> "dbdc2234-7322-11e9-b5c9-30e37a55bab4");

ectool

syntax:

ectool getAllWaitingTasks <projectName> <releaseName>

ectool getAllWaitingTasks <flowRuntimeId>

Example

ectool getAllWaitingTasks --projectName "proj1" --releaseName "release1"
ectool getAllWaitingTasks --flowRuntimeId "dbdc2234-7322-11e9-b5c9-30e37a55bab4"

getAttachedPipelineRuns

Fetch all attached runs for the specified release.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release from which to fetch pipeline runs.

Argument Type: String

Positional arguments

projectName

Response

Returns an AttachedPiplineRunDetail object.

ec-perl

syntax: $<object>->getAttachedPipelineRuns (<projectName>, {releaseName ⇒ <release_name>});

Example

$ec->getAttachedPipelineRuns("Default", {releaseName => AugustRelease});

ectool

syntax: ectool getAttachedPipelineRuns <projectName> --releaseName <release_name>

Example

ectool getAttachedPipelineRuns "Default" --releaseName "AugustRelease"

getDeployerApplication

Retrieves the application used in the Release by name.

You must specify the projectName and applicationName arguments.

Arguments Descriptions

projectName

Name of the project in which releaseName resides.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

applicationProjectName

(Optional) The name of the project containing specified application. If this argument is not specified, the default is the Release project.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument type: String

Positional arguments

projectName, applicationName

Response

Returns a Deployer application object.

ec-perl

syntax: $<object>->getDeployerApplication(<projectName>, <applicationName>, {<optionals>});

Example

$ec->getDeployerApplication("Default", "Verify versions", {applicationProjectName => "Quarterly Summaries"});

ectool

syntax: ectool getDeployerApplication <projectName> <applicationName> [optionals]

Example

ectool getDeployerApplication "Default" "Verify versions" --applicationProjectName "Quarterly Summaries"

getDeployerApplications

Retrieves all the applications in a Release.

You must specify the projectName argument.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName

Response

Returns all the Deployer application objects.

ec-perl

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

Example

$ec->getDeployerApplications ("Default", {releaseName => "Weekly Build"});

ectool

syntax: ectool getDeployerApplications <projectName> [optionals]

Example

ectool getDeployerApplications "Default" --releaseName "Weekly Build"

getDeployerConfiguration

Retrieves a Deployer configuration.

You must specify the projectName, applicationName, and stageName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

stageName

Name of the pipeline stage attached to a Release if the Release is specified.

Argument Type: String

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the release project name.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName, applicationName, stageName

Response

Returns the Deployer configuration object.

ec-perl

syntax: $<object>->getDeployerConfiguration(<projectName>, <applicationName>, <stageName>, {<optionals>});

Example

$ec->getDeployerConfiguration("Default", "Shopping Cart", "QA", {applicationProjectName => "Quarterly Summaries"});

ectool

syntax: ectool getDeployerConfiguration <projectName> <applicationName> <stageName> [optionals]

Example

ectool getDeployerConfiguration "Default" "Shopping Cart" "QA" --applicationProjectName "Quarterly Summaries"

getDeployerConfigurations

Retrieves all the configurations in the Deployer.

You must specify the projectName argument.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

(Optional) Name of the application.

Argument Type: String

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the release project name.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

stageName

(Optional) Name of the pipeline stage attached to a Release if the Release is specified.

Argument Type: String

Positional arguments

projectName

Response

Returns the list of Deployer configuration objects.

ec-perl

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

Example

$ec->getDeployerConfigurations("Default", {applicationProjectName => "Quarterly Summaries"});

ectool

syntax: ectool getDeployerConfigurations <projectName> [optionals]

Example

ectool getDeployerConfigurations "Default" --applicationProjectName "Quarterly Summaries"

getGate

Retrieves a gate by its stage name and gate type.

You must specify the projectName, stageName, and gateType.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

gateType

Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, stageName, gateType

Response

Returns a pipeline gate object.

ec-perl

syntax: $<object>->getGate(<projectName>, <stageName>, <gateType>, {<optionals>});

Example

$ec->getGate("Default", "Preflight", POST, {pipelineName => "Quarterly Summary"});

ectool

syntax: ectool getGate <projectName> <stageName> <gateType> [optionals]

Example

ectool getGate "Default" "Preflight" POST --pipelineName "Quarterly Summary"

getNote

Retrieves a note associated with an entity.

You must specify the noteName argument.

Arguments Descriptions

noteName

Name of the note.

Argument Type: String

projectName

(Optional) Project name of the entity that owns the note.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

noteName

Response

Returns the selected note.

ec-perl

syntax: $<object>->getNote(<noteName>, {<optionals>});

Example

$ec->getNote("Final Approval", {releaseName => "Production"});

ectool

syntax: ectool getNote <noteName> [optionals]

Example

ectool getNote "Final Approval" --releaseName "Production"

getNotes

Retrieves all the notes associated with an entity.

Arguments Descriptions

projectName

(Optional) Project name of the entity that owns the note.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

noteName

Response

Returns all the notes for a release.

ec-perl

syntax: $<object>->getNote({<optionals>});

Example

$ec->getNote({releaseName => "Production"});

ectool

syntax: ectool getNote [optionals]

Example

ectool getNote --releaseName "Production"

getPipeline

Retrieves a pipeline by its name.

You must specify the projectName and pipelineName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

Name of the pipeline that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, pipelineName

Response

Returns the specified pipeline element.

ec-perl

syntax: $<object>->getPipeline(<projectName>, <pipelineName>);

Example

$ec->getPipeline("Default", "Dev to Prod");

ectool

syntax: ectool getPipeline <projectName> <pipelineName>

Example

ectool getPipeline "Default" "Dev to Prod"

getPipelineRuntimeDetails

Retrieves pipeline runtime details.

Arguments Descriptions

flowRuntimeIds

(Optional) List of the pipeline flow runtime IDs.

Type: Collection of UUIDs

Positional arguments

None

Response

Returns flowRuntime object that includes runtime details of the flow and these flags:

completed

1—The pipeline or release run is complete.

restartable

1—The pipeline run has at least one stage or task that can be restarted.

waitingForApproval

1—The pipeline run is waiting on a manual stage or gate task.

waitingForManualRetry

1—The pipeline run is waiting on one or more manual retry tasks.

ec-perl

syntax: $<object>->getFlowRuntimeDetails({<optionals>});

Example

$ec->getFlowRuntimeDetails({flowRuntimeIds => "f1b9470b-d0cb-11e8-bdbc-10653022f566" "f1d9c7f9-d0cb-11e8-8e13-10653022f566"});

ectool

syntax: ectool getFlowRuntimeDetails [optionals]

Example

ectool getFlowRuntimeDetails --flowRuntimeIds "f1b9470b-d0cb-11e8-bdbc-10653022f566" "f1d9c7f9-d0cb-11e8-8e13-10653022f566"

getPipelineRuntimes

Retrieves pipeline runs.

Arguments Descriptions

filters

(Optional) A list of zero or more filter criteria definitions used to define objects to find.

Because of the complexity of specifying filter criteria, this argument is not supported via ectool. Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD Perl API. Two types of filters: "property filters" are used to select objects based on the value of the object’s intrinsic or custom property. "boolean filters" ("and", "or", "not") are used to combine one or more filters using boolean logic. Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property. Property filter operators are:

between (2 operands)

contains (1)

equals (1)

greaterOrEqual (1)

greaterThan (1)

in (1)

lessOrEqual (1)

lessThan (1)

like (1)

notEqual (1)

notLike (1)

isNotNull (0)

isNull (0)

A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter. Boolean operators are:

not (1 operand)

and (2 or more operands)

or (2 or more operands)

Argument type: Collection

firstResult

(Optional) First row of the results to return, based on how the results are paginated.

Argument Type: Integer

flowRuntimeId

(Optional) ID of the flow runtime.

Argument Type: UUID

flowRuntimeName

(Optional) Name of the flow runtime.

Argument Type: String

maxResults

(Optional) The number of rows to return, based on how the results are paginated.

Argument Type: Integer

pipelineName

(Optional) Name of the pipeline.

Argument Type: String

projectName

(Optional) Name of the project to which the pipeline or release belongs.

Argument Type: String

releaseId

(Optional) ID of the release.

Argument Type: String

sortKey

(Optional) How to sort the results.

Argument Type: String

sortOrder

(Optional) The order in which the results are sorted.

Argument Type: SortOrder

statusExcludes

(Optional) List of statuses to exclude from the response.

Argument Type: Collection

Positional arguments

None

Response

Returns a flowRuntime object.

ec-perl

syntax: $<object>->getPipelineRuntimes({<optionals>});

Example

$ec->getPipelineRuntimes({pipelineName => "Pre-production", projectName => "Default"});

ectool

syntax: ectool getPipelineRuntimes [optionals]

Example

ectool getPipelineRuntimes --pipelineName "Pre-production" --projectName "Default"

getPipelineStageRuntimeDeployerTasks

Retrieves the list of Deployer tasks and their details to be displayed in Pipeline Run Details page.

You must specify the flowRuntimeId, stageName, and taskName.

Arguments Descriptions

flowRuntimeId

ID of the flow runtime.

Argument Type: UUID

stageName

The name of the stage.

Argument Type: String

taskName

The name of the Deployer task.

Argument Type: String

firstResult

(Optional) First row of the results to return, based on how the results are paginated.

Argument Type: Integer

groupRunNumber

(Optional) The group run number.

Argument TYpe: Number

maxResults

(Optional) The number of rows to return, based on how the results are paginated.

Argument Type: Integer

sortKey

(Optional) How to sort the results.

Argument Type: String

sortOrder

(Optional) The order in which the results are sorted.

Argument Type: SortOrder

stageRunNumber

(Optional) The stage run number.

Argument Type: Number

taskRunNumber

(Optional) The task run number.

Argument Type: Number

Positional arguments

flowRuntimeId, stageName, taskName

Response

Returns a list of Deployer tasks for a pipeline stage and the details about them.

ec-perl

syntax: $<object>->getPipelineStageRuntimeDeployerTasks(<flowRuntimeId>, <stageName>, <taskName>, {<optionals>});

Example

$ec->getPipelineStageRuntimeDeployerTasks(4fa765dd-73f1-11e3-b67e-b0a420524165, "PROD", "Deploy WAR file", {firstResult => 2, maxResults => 200});

ectool

syntax: ectool getPipelineStageRuntimeDeployerTasks <flowRuntimeId> <stageName> <taskName> [optionals]

Example

ectool getPipelineStageRuntimeDeployerTasks 4fa765dd-73f1-11e3-b67e-b0a420524165 "PROD" "Deploy WAR file" --firstResult 2 --maxResults 200

getPipelineStageRuntimeTasks

Retrieves the list of pipeline stage tasks and the details about them that are displayed in the pipeline run view.

You must specify the flowRuntimeId

Arguments Descriptions

flowRuntimeId

ID of the flow runtime.

Argument Type: UUID

firstResult

(Optional) First row of the results to return, based on how the results are paginated.

Argument Type: Integer

maxResults

(Optional) The number of rows to return, based on how the results are paginated.

Argument Type: Integer

sortKey

(Optional) How to sort the results.

Argument Type: String

sortOrder

(Optional) The order in which the results are sorted.

Argument Type: SortOrder

stageName

Name of the stage.

Argument Type: String

stageRunNumber

The stage run number.

Argument Type: Number

Positional arguments

flowRuntimeId

Response

Returns a list of pipeline task objects and the details about them in the pipeline run view.

ec-perl

syntax: $<object>->getPipelineStageRuntimeTasks (<flowRuntimeId>, {<optionals>});

Example

$ec->getPipelineStageRuntimeTasks(4fa765dd-73f1-11e3-b67e-b0a420524165, {firstResult => 2, maxResults => 200});

ectool

syntax: ectool getPipelineStageRuntimeTasks <flowRuntimeId> [optionals]

Example

ectool getPipelineStageRuntimeTasks 4fa765dd-73f1-11e3-b67e-b0a420524165 --firstResult 2 --maxResults 200

getPipelines

Retrieves all the pipelines.

You must specify the projectName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

Positional arguments

projectName

Response

Returns all of the pipelines in a project.

ec-perl

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

Example

$ec->getPipelines("Default");

ectool

syntax: ectool getPipelines <projectName>

Example

ectool getPipelines "Default"

getRelease

Retrieves a Release by name.

You must specify the projectName and the releaseName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, releaseName

Response

Returns the selected Release.

ec-perl

syntax: $<object>->getRelease(<projectName>, <releaseName>);

Example

$ec->getRelease("Default", "Production");

ectool

syntax: ectool getRelease <projectName> <releaseName>

Example

ectool getRelease "Default" "Production"

getReleaseInventory

Retrieves the artifact inventory created in a release.

You must specify the projectName and the releaseName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, releaseName

Response

Returns a per-release grouped list of inventoryDetail elements, as well as an environmentInventoryDetail element containing the latest deployment details present in the environment. This can be either same as one of the inventoryDetail elements or it could be different if there was a deployment for the application that happened after the deployment of the application from the release.

ec-perl

syntax: $<object>->getReleaseInventory(<projectName>, <releaseName>);

Example

$ec->getReleaseInventory("Default", "Production");

ectool

syntax: ectool getReleaseInventory <projectName> <releaseName>

Example

ectool getReleaseInventory "Default" "Production"

getReleases

Retrieves all releases.

You must specify the projectName for backward compatibility in CloudBees CD versions before CloudBees CD 6.2.

Arguments Descriptions

projectName

(Optional) Name of the project to which the release belongs.

Use this as a positional argument in CloudBees CD versions before CloudBees CD 6.2 for backward compatibility.

Argument Type: String

filters

(Optional) A list of zero or more filter criteria definitions used to define objects to find. Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD Perl API. Two types of filters: "property filters" are used to select objects based on the value of the object’s intrinsic or custom property. "boolean filters" ("and", "or", "not") are used to combine one or more filters using boolean logic. Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property. Property filter operators are:

between (2 operands)

contains (1)

equals (1)

greaterOrEqual (1)

greaterThan (1)

in (1)

lessOrEqual (1)

lessThan (1)

like (1)

notEqual (1)

notLike (1)

isNotNull (0)

isNull (0)

A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter. Boolean operators are:

not (1 operand)

and (2 or more operands)

or (2 or more operands)

Argument type: Collection

firstResult

(Optional) First row of the results to return, based on how the results are paginated.

Argument Type: Integer

maxResults

(Optional) The number of rows to return, based on how the results are paginated.

Argument Type: Integer

releaseFlowRuntimeMappings

(Optional) Map of releaseId and flowRuntimeId.

Argument Type: Map

sortKey

(Optional) How to sort the results.

Argument Type: String

sortOrder

(Optional) The order in which the results are sorted.

Argument Type: SortOrder

Positional arguments

projectName for backward compatibility in CloudBees CD versions before CloudBees CD 6.2.

Response

Returns a list of release objects, where each object includes pipeline stage tasks, details about them in the pipeline run view, and these flags:

allowCurrentUserToApprove

1—The logged in user is allowed to approve a waiting task in a stage or gate.

completed

1—The pipeline is complete.

waitingForApproval

1—The release is waiting on a manual stage or gate task.

waitingForManualRetry

1—The release is waiting on one or more manual retry tasks.

waitingOnManual

1—The release is waiting on a manual stage task.

ec-perl

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

Example

$ec->getReleases("Default", {firstResult => 2, maxResults => 200});

ectool

syntax: ectool getReleases <projectName> [optionals]

Example

ectool getReleases "Default" --firstResult 2 --maxResults 200

getReleaseTimelineDetails

Retrieves planned versus actual time details for a release.

You must specify the projectName and the releaseName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, releaseName.

Response

Returns the planned versus actual time details for a release

ec-perl

syntax: $<object>->getReleases(<projectName>, <releaseName>);

Example

$ec->getReleases("Default", "First Quarter");

ectool

syntax: ectool getReleases <projectName> <releaseName>

Example

ectool getReleases "Default" "First Quarter"

getRunHierarchy

Returns either the definition view or the runtime view for the specified release.

Arguments Descriptions

filters

(Optional) A list of zero or more filter criteria definitions used to define objects in the hierarchy bounded by the top-level release, pipeline, or runtime.

Note: Because of the complexity of specifying filter criteria, this argument is not supported via ectool. Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD Perl API. Two types of filters: "property filters" are used to select objects based on the value of the object’s intrinsic or custom property. "boolean filters" ("and", "or", "not") are used to combine one or more filters using boolean logic. Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property. Property filter operators are:

between (2 operands)

contains (1)

equals (1)

greaterOrEqual (1)

greaterThan (1)

in (1)

lessOrEqual (1)

lessThan (1)

like (1)

notEqual (1)

notLike (1)

isNotNull (0)

isNull (0)

A boolean filter is a boolean operator and an array of one or more filters that are operands. Each operand can be either a property filter or a boolean filter. Boolean operators are:

not (1 operand)

and (2 or more operands)

or (2 or more operands)

Argument type: Collection

flowRuntimeId

Used for the runtime view of the hierarchy: the ID of the flow runtime representing the pipeline run.

Argument Type: UUID

mode

The format in which the data is returned.

  • HIERARCHY –(default) Nested view of releases and pipelines. This corresponds to the release or pipeline portfolio view in the UI.

  • LIST –Linear list of releases and pipelines in the order in which they run. Only first-level children are returned. This mode corresponds to the pipeline or release portfolio list view in the UI.

Argument Type: String

pipelineName

Used for definition view of the hierarchy: the name of the pipeline definition.

Argument Type: String

projectName

The name of the project in which the pipelineName or releaseName definition resides.

Argument Type: String

releaseName

Used for definition view of the hierarchy: the name of the release.

Argument Type: String

Positional arguments

None.

Response

A runDetail object representing the hierarchy.

ec-perl

syntax:

$<object>->getRunHierarchy(projectName ⇒ <project_name>, {pipelineName ⇒ pipeline_name | releaseName ⇒ <release_name>});

$<object>->getRunHierarchy(flowRuntimeId ⇒ <flow_runtime_id>);

Example for release definition view

$ec->getRunHierarchy(projectName=> "Default", releaseName => AugustRelease);

Example for pipeline definition view

$ec->getRunHierarchy(projectName=> "Default", pipelineName => "Pipeline A");

Example for runtime view

$ec->getRunHierarchy(flowRuntimeId => e9bebbe3-c087-11e9-8bf5-001c42c3ce23);

ectool

syntax:

ectool getRunHierarchy --projectName <project_name>, {--pipelineName pipeline_name | --releaseName <release_name>}

ectool getRunHierarchy --flowRuntimeId <flow_runtime_id>

Example for release definition view

ectool getRunHierarchy --projectName "Default" --releaseName "AugustRelease"

Example for pipeline definition view

ectool getRunHierarchy --projectName "Default" --pipelineName "Pipeline A"

Example for runtime view

ectool getRunHierarchy --flowRuntimeId e9bebbe3-c087-11e9-8bf5-001c42c3ce23

getStage

Retrieves a stage by its name.

You must specify the projectName and stageName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, stageName

Response

Returns a stage element.

ec-perl

syntax: $<object>->getStage(<projectName>, <stageName>, {<optionals>});

Example

$ec->getStage("Default", "Preflight", {pipelineName => "Final"});

ectool

syntax: ectool getStage <projectName> <stageName> [optionals]

Example

ectool getStage "Default" "Preflight" --pipelineName "Final"

getStages

Retrieves all the stages for a pipeline.

You must specify the projectName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName

Response

Returns all the stages for a pipeline.

ec-perl

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

Example

$ec->getStages("Default", {pipelineName => "Final"});

ectool

syntax: ectool getStages <projectName> [optionals]

Example

ectool getStages "Default"  --pipelineName "Final"

getTask

Retrieves a task by its name.

You must specify the projectName and taskName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

taskName

Name of the task.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

releaseName

Name of the release.

Argument Type: String

stageName

(Optional) Name of the stage to which this task belongs.

Argument type: String

Positional arguments

projectName, taskName

Response

Returns a task object.

ec-perl

syntax: $<object>->getTask(<projectName>, <taskName>, {<optionals>});

Example

$ec->getTask("Default", "Check out files", {pipelineName => "Final"});

ectool

syntax: ectool getTask <projectName> <taskName> [optionals]

Example

ectool getTask "Default" "Check out files" --pipelineName "Final"

getTasks

Retrieves all tasks.

You must specify the projectName argument.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

releaseName

Name of the release.

Argument Type: String

stageName

(Optional) Name of the stage to which this task belongs.

Argument type: String

Positional arguments

projectName

Response

Returns all the task objects for a pipeline.

ec-perl

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

Example

$ec->getTasks("Default", {pipelineName => "Final"});

ectool

syntax: ectool getTasks <projectName> [optionals]

Example

ectool getTasks "Default" --pipelineName "Final"

getWaitingTasks

Retrieves a list of all the stage tasks that are currently waiting on manual and waiting for manual retry tasks in pipeline run view.

You must specify the flowRuntimeId and stageName argument.

Arguments Descriptions

flowRuntimeId

The ID of the flow runtime.

Argument type: UUID

stageName

Name of the stage.

Argument type: String

TaskName

(Optional) The name of the deployer task.

Argument type: String

Positional arguments

flowRuntimeId and stageName

Response

Returns all waiting task objects for a pipeline.

ec-perl

syntax: $<object>->getWaitingTasks(<flowRuntimeId>, <stageName>, {<optionals>});

Example

$ec->getWaitingTasks("5da765dd-73f1-11e3-b67e-b0a420524153", "PROD", {sortKey => start, sortOrder => ascending});

ectool

syntax: ectool getWaitingTasks <projectName> <stageName> [optionals]

Example

ectool getWaitingTasks "5da765dd-73f1-11e3-b67e-b0a420524153" "PROD" --sortKey start --sortOrder ascending

modifyDeployer

Modifies an existing Deployer.

You must specify the projectName and the deployerName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

deployerName

Name of the Deployer that must be unique within the project.

Argument Type: String

newName

(Optional) New name for the existing Deployer.

Argument Type: String

Positional arguments

projectName, deployerName

Response

Returns an updated Deployer element.

ec-perl

syntax: $<object>->modifyDeployer(<projectName>, <deployerName>, {<optionals>});

Example

$ec->modifyDeployer("Default", "Deploy Shopping Cart", {newName => "Shopping Cart"});

ectool

syntax: ectool modifyDeployer <projectName> <deployerName> [optionals .]

Example

ectool modifyDeployer "Default" "Deploy Shopping Cart" --newName "Shopping Cart"

modifyDeployerApplication

Modifies the Deployer application associated with a Release.

You must specify the projectName and applicationName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

applicationProjectName

(Optional) The name of the project containing specified application. If not specified, it is defaulted to the Release project name.

Argument Type: String

errorHandling

(Optional) The error handling method for the Deployer application.

Argument Type: FlowStateErrorHandling

orderIndex

(Optional) The application deployment order, starting at 1.

Argument type: Integer

processName

(Optional) Name of the process.

Argument type: String

releaseName

(Optional) Name of the release.

Argument type: String

smartDeploy

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

If this is set to 1 or true, the smart deploy option is used when the application is deployed.

Argument type: Boolean

snapshotName

(Optional) Name of the snapshot.

Argument type: String

stageArtifacts

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, artifact staging is enabled for the application process. CloudBees CD retrieves artifacts that will be deployed in an application run before the deployment starts.

When this argument is set to false or 0, artifact staging is disabled.

Argument Type: Boolean

Positional arguments

projectName, applicationName

Response

Returns a modified Deployer application and its details.

ec-perl

syntax: $<object>->modifyDeployerApplication(<projectName>, <applicationName>, {<optionals>});

Example

$ec->modifyDeployerApplication("Default", "Verify versions", {smartDeploy => 1});

ectool

syntax: ectool modifyDeployerApplication <projectName> <applicationName> [optionals]

Example

ectool modifyDeployerApplication "Default" "Verify versions" --smartDeploy 1

modifyDeployerConfiguration

Modifies a Deployer configuration associated with a Deployer application.

You must specify the projectName, applicationName, and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

stageName

Name of the stage of a pipeline that is attached to a Release when a Release is specified.

Argument Type: String

actualParameters

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

Argument Type: Map

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the Release project name.

Argument Type: String

clearActualParameters

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

If this is set to 1 or true, all actual parameters are removed.

Argument type: Boolean

environmentName

(Optional) The name of the environment.

Argument Type: String

environmentProjectName

(Optional) The name of the project containing specified environment or environment template. If this argument is not specified,the default is the Release project name.

Argument Type: String

environmentTemplateName

(Optional) Name of the environment template.

Argument Type: String

environmentTemplateProjectName

(Optional) Name of the project containing specified environment template. If this argument is not specified, the default is the environment project name.

Argument Type: String

insertRollingDeployManualStep

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 a manual step needs to be added after each phase or batch is run.

Argument type: Boolean

releaseName

(Optional) Name of the release.

Argument Type: String

rollingDeployEnabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 the pipeline runs the rolling deployment.

Argument type: Boolean

rollingDeployManualStepAssignees

(Optional) A list of assignees who receive the notification when the rolling deploy iteration is completed.

Argument type: Collection

rollingDeployManualStepCondition

(Optional) The Run if condition (run condition) on the manual step that was created during the rolling deployment.

Argument type: NotificationType

rollingDeployPhases

(Optional) One or more rolling deploy phases to be used in the rolling deployment.

Argument type: Collection

skipDeploy

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the application is not deployed to an environment.

Argument type: Boolean

Positional arguments

projectName, applicationName, stageName

Response

Returns the Deployer configuration and its details.

ec-perl

syntax: $<object>->modifyDeployerConfiguration(<projectName>, <applicationName>, <stageName>,{<optionals>});

Example

$ec->modifyDeployerConfiguration("Default", "Shopping Cart", "Publish components", {applicationProjectName => "Online store"});

ectool

syntax: ectool modifyDeployerConfiguration <projectName> <applicationName> <stageName> [optionals]

Example

ectool modifyDeployerConfiguration "Default" "Shopping Cart" "Publish components" --applicationProjectName "Online store"

modifyGate

Modifies an existing gate.

You must specify the projectName, stageName, and gateType.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

gateType

Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing the next stage. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. An \"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)]

Argument Type: String

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

precondition

(Optional) A property that allows the stage to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition)is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

Name of the release.

Argument Type: String

Positional arguments

projectName, stageName, gateType

Response

Returns a modified gate object.

ec-perl

syntax: $<object>->modifyGate(<projectName>, <stageName>, <gateType>, {<optionals>});

Example

$ec->modifyGate("Default", "Preflight", POST, {pipelineName => "Annual Summary"});

ectool

syntax: ectool modifyGate <projectName> <stageName> <gateType> [optionals]

Example

ectool modifyGate "Default" "Preflight" POST --pipelineName "Annual Summary"

modifyNote

Modifies a note associated with an entity.

You must specify the noteName argument.

Arguments Descriptions

noteName

Name of the note.

Argument Type: String

newName

(Optional) New name for the note.

Argument Type: String

note

(Optional) Notes about the entity.

Argument Type: String

projectName

(Optional) Project name of the entity that owns the note.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

noteName

Response

Returns a modified note object.

ec-perl

syntax: $<object>->getNote(<noteName>, {<optionals>});

Example

$ec->getNote("Final Approval", {note => "Not approved until all tests are run"});

ectool

syntax: ectool getNote <noteName> [optionals]

Example

ectool getNote "Final Approval" --note "Not approved until all tests are run"

modifyPipeline

Modifies an existing pipeline.

You must specify the projectName and the pipelineName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

Name of the pipeline that must be unique within the project.

Argument Type: String

assigneesForSkipStage

(Optional) A list of users who can skip stages at runtime.

Argument Type: Collection

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

disableMultipleActiveRuns

(Optional) Control whether more than one active run is allowed for this pipeline.

If true or 1, disable ability to have more than one active run for this pipeline.

If false or 0, enable ability to have more than one active run for this pipeline. (default)

Argument Type: Boolean

disableRestart

(Optional) Control whether pipeline can be restarted.

If true or 1, disable ability to restart pipeline.

If false or 0, enable ability to restart pipeline. (default)

Argument Type: Boolean

enabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the pipeline is enabled.

Argument type: Boolean

newName

(Optional) New name for an existing pipeline.

Argument Type: String

overrideWorkspace

(Optional) Control whether tasks use pipeline’s workspace

If true or 1, and workspaceName is not NULL, then all tasks use this pipeline’s workspace.

If If false or 0, tasks use original workspace. (default)

Argument type: Boolean

pipelineRunNameTemplate

(Optional) Template for the pipeline run name. If not specified, the pipeline run name is constructed from pipelineName.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

skipStageMode

(Optional) The flag to indicate if stages can be skipped at runtime.

Argument Type: StageSkipMode

type

(Optional) Type of pipeline.

Argument Type: PipelineType

workspaceName

(Optional) The name of the workspace.

Argument Type: String

Positional arguments

projectName, pipelineName

Response

Returns a modified pipeline object.

ec-perl

syntax: $<object>->modifyPipeline(<projectName>, <pipelineName>, {<optionals>});

Example

To change the pipeline name:

$ec->modifyPipeline("Default", "Web Site Deploy", {newName => "Web Site Update"});

ectool

syntax: ectool modifyPipeline <projectName> <pipelineName> [optionals]

Example

To change the pipeline name:

ectool modifyPipeline "Default" "Web Site Deploy" --newName "Web Site Update"

modifyRelease

Modifies an existing release. When the pipelineName and pipelineProjectName arguments are provided, the existing pipeline associated with the release is deleted, and the resolved pipeline is cloned to a new pipeline under the new release.

You must specify the projectName and the releaseName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

actualParameters

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

Argument Type: Map

clearActualParameters

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

If set to true, tasks remove all actual parameters.

Argument type: Boolean

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

This text is not interpreted by the automation platform.

Argument type: String

disableMultipleActiveRuns

(Optional) Control whether more than one active run is allowed for this release pipeline .

If true or 1, disable ability to have more than one active run for this release pipeline.

If false or 0, enable ability to have more than one active run for this release pipeline. (default)

Argument Type: Boolean

disablePipelineRestart

(Optional) Control whether pipeline can be restarted.

If true or 1, disable ability to restart pipeline.

If false or 0, enable ability to restart pipeline. (default)

Argument Type: Boolean

newName

(Optional) New name for an existing pipeline.

Argument Type: String

overrideWorkspace

(Optional) Control whether tasks use release pipeline’s workspace

If true or 1, and workspaceName is not NULL, then all tasks use this release pipeline’s workspace.

If If false or 0, tasks use original workspace. (default)

Argument type: Boolean

pipelineName

(Optional) Name of the pipeline.

Argument Type: String

pipelineProjectName

(Optional) Name of the project containing specified pipeline. If this argument is not specified, the default is the Release project name.

Argument Type: String

pipelineWorkspaceName

(Optional) The name of the release pipeline workspace.

Argument Type: String

plannedEndDate

(Optional) The date when this release is expected to end (for example, 2016-05-15).

Argument Type: String

plannedStartDate

(Optional) The date when this release is expected to begin (for example, 2016-05-15)

Argument Type: String

timeZone

(Optional) The time zone to use for this release. If not specified, the user’s time zone is used.

Argument Type: String

Positional arguments

projectName, releaseName

Response

Returns a modified release object.

ec-perl

syntax: $<object>->modifyRelease(<projectName>, <releaseName>, {<optionals>});

Example

$ec->modifyRelease("Default", "Production", {pipelineName => "Q2 Summary"});

ectool

syntax: ectool modifyRelease <projectName> <releaseName> [optionals]

Example

ectool modifyRelease "Default" "Production" --pipelineName "Q2 Summary"

modifyStage

Modifies an existing stage.

You must specify the projectName and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

stageName

Name of the stage.

Argument Type: String

afterStage

(Optional) The stage that is placed after the new stage.

Argument Type: String

beforeStage

(Optional) The stage that is placed before the new stage.

Argument Type: String

colorCode

(Optional) The hexadecimal value of the color to be used with an entity.

Argument Type: String

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing to the next stage. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "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)]

Argument Type: String

description

(Optional) Comment text describing this object; it is not interpreted at all by CloudBees CD .

Argument Type: String

newName

(Optional) New name for the existing stage.

Argument Type: String

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

precondition

(Optional) A property that allows the stage to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition)is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

Name of the release.

Positional arguments

projectName, stageName

Response

Returns a modified stage object.

ec-perl

syntax: $<object>->modifyStage(<projectName>, <stageName>, {<optionals>});

Example

To modify the name of the stage, enter:

$ec->modifyStage("Default", "PROD", {newName => "PROD 2"});

To modify the Wait until condition (precondition) so that the "Automated Tests" stage is completed before running the "UAT demo" stage, enter:

$ec->modifyStage("Default", "UAT demo", {precondition => "$[/myPipelineRuntime/autoTestCompleted]"});

To modify the Run if condition (run condition) that the name of the next stage after the "Preflight" stage is "UATdemo", enter:

$ec->modifyStage("Default", "Preflight", {condition => "$[/javascript (myPipelineRuntime.pipelineName == myPipelineRuntime.UATdemo)]"});

ectool

syntax: ectool modifyStage <projectName> <stageName> [optionals]

Example

To modify the name of the stage, enter:

ectool modifyStage "Default" "PROD" --newName "PROD 2"

To modify the Wait until condition (precondition) so that the "Automated Tests" stage is completed before running the "UAT demo" stage, enter:

ectool modifyStage "Default" "UAT demo" --precondition "$[/myPipelineRuntime/autoTestCompleted]"

To modify the Run if condition (run condition) that the name of the next stage the "Preflights" stage is "UATdemo", enter:

ectool modifyStage "Default" "Preflight" --condition => "$[/javascript (myPipelineRuntime.pipelineName == myPipelineRuntime.UATdemo)]"

modifyTask

Modifies an existing task.

You must specify the projectName and taskName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

taskName

Name of the task.

Argument Type: String

actionLabelText

The JSON string used to assign custom label text to manual task or approval gate rule actions.

{
   "completed":"",
   "failed":"",
   "skipped":""
}

Where:

  • completedLabel —used for successful outcome; default label for manual tasks is Completed, default label for approval gate rules is Approve.

  • failedLabel —used for unsuccessful outcome; default label for manual tasks is Failed, default label for approval gate rules is Reject.

  • skippedLabel —used for task skipping; default label for manual tasks is Skip this task, default label for approval gate rules is Skip this gate.

Argument Type: String

actualParameters

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

Argument Type: Map

advancedMode

(Optional) < Boolean flag0|1|true|false >

When advancedMode is set to true or 1, advanced mode is enabled so that all validations for the applicationName, environmentName, processName, or snapshotName will be skipped. These objects can be represented using the " $[] " notation and later expanded at the pipeline runtime. For example, when advancedMode is enabled, the system does not validate that the environment exists or whether it is mapped to an application.

Argument type: Boolean

afterLastRetry

(Optional) <continueOnError|stopOnError> ]

Specifies whether to continue or stop pipeline execution after the last unsuccessful retry of a task. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is stopOnError.

Argument Type: AfterLastRetryErrorHandling

afterTask

(Optional) The task that is placed after the new task.

Argument Type: String

allowOutOfOrderRun

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task can be run out of order.

Argument type: Boolean

alwaysRun

(Optional) true means this task will run even if preceding tasks fail in a way that abort the pipeline. This lets you define an "always run" task, which will run regardless of the error handling behavior for any preceding tasks. This facility is most commonly used for cleanup operations at the end of a stage or gate.

Argument Type: Boolean

allowSkip

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task can be skipped at runtime—only users specified in the approver list will be allowed to skip. Available when taskType = { MANUAL, APPROVAL }.

Argument type: Boolean

approvers

(Optional) <approver1> <approver2> …​

A list of task approvers who receive the notification. This can be provided for APPROVAL and MANUAL types of task and for any other type of task if errorHandling for the task is set to retryOnError and retryType is set to manual.

Argument Type: Collection

beforeTask

(Optional) The task that is placed before the new task.

Argument Type: String

clearActualParameters

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

If set to true or 1, all the actual parameters are removed from the flow.

Argument type: Boolean

ciConfigurationName

Name of the CI configuration containing for the Jenkins master of interest.

Must be specified when taskType = CI_JOB.

Argument Type: String

ciJobFolder

Path to the folder on the CI server referenced by ciConfigurationName that contains the specified CI job. Must be in format folder1/folder2/folder3/…​. Available when taskType = CI_JOB.

If not specified, root folder for the Jenkins Master is used.

Argument Type: String

ciJobName

Name of the CI job to run for this task.

Must be specified when taskType = CI_JOB.

Argument Type: String

clearOutOfOrderRunAssignees

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, clear the list of out-of-order run assignees and allow all users to run this task out of order.

Argument type: Boolean

condition

(Optional) The Run if condition (run condition) is property reference that the pipeline evaluates before executing the next task. The pipeline waits until one or more dependent run conditions are met. By default, no run conditions are set.

The run condition is "fixed text" or text embedding property references that are evaluated into a logical TRUE or FALSE. An \"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)]

credentials

(Optional) The credentials to be used in the task.

Argument type: Collection

description

(Optional) Comment text describing this object; not interpreted at all by CloudBees CD .

Argument Type: String

disableFailure

(Optional) < Boolean flag0|1|true|false >(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 this task cannot be failed—it will always complete with success. Available when taskType = MANUAL.

Argument type: Boolean

emailConfigName

(Optional) The name of email configuration.

Argument Type: String

enabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the task is enabled.

Argument type: Boolean

environmentName

(Optional) Name of the environment to create from a template.

When the environmentTemplateName is specified, the environmentName can be specified using the " $[] " notation. It is expanded at runtime.

Argument Type: String

environmentProjectName

(Optional) Name for the project to which the environment or environment template belongs.

Argument Type: String

environmentTemplateName

(Optional) Name of the environment template.

When the environmentTemplateName is specified, the environmentName can be specified using the " $[] " notation. It is expanded at runtime.

Argument Type: String

environmentTemplateProjectName

(Optional) Name of the project containing specified environment template. If this argument is not specified, the default is the environment project name.

Argument Type: String

errorHandling

(Optional) <continueOnError|retryOnError|stopOnError>

Type of error handling for this task.

Argument Type: FlowStateErrorHandling

firstTask

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, this task is the first task in the stage, and the beforeTask and afterTask arguments should not be used. The default is false or 0.

Argument type: Boolean

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

insertRollingDeployManualStep

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 a manual step needs to be added after each phase or batch is run.

Argument type: Boolean

instruction

(Optional) Instruction associated with the task.

Argument type: String

keepOnError

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the system is set to keep environment if an error occurs. The default is false or 0.

Argument type: Boolean

newName

(Optional) New name for an existing task.

Argument Type: String

notificationTemplate

(Optional) String containing email formatting instructions for generating notifications. This can be used only for APPROVAL and MANUAL types of task and for any other type of task that has errorHandling set to retryOnError and retryType set to manual.

Argument type: String

outOfOrderRunAssignees

(Optional) A list of one or more users who can run this task out of order. If not specified, all users can run the task out of order.

pipelineName

(Optional) Name of the pipeline to which the stage belongs.

Argument type: String

plannedEndDate

plannedStartDate

(Optional) Set the start and end times for a PRE or POST gate.

precondition

(Optional) A property that allows the task to be created with "pause", which then pauses the pipeline at that point. The pipeline waits until one or more dependent conditions are met.

When the pipeline status is eligible to transition from pending to runnable, a Wait until condition (precondition)is evaluated. The precondition is fixed text or text embedding a 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 pipeline does not progress until the condition is TRUE.

By default, this condition is not set and is FALSE.

Argument type: String

releaseName

Name of the release.

Argument Type: String

retryCount

(Optional) Specifies the maximum number of times that the retry should occur. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is 3.

Argument type: String

retryinterval

(Optional) Specifies the number of seconds to wait until the next retry. This can be used only for a task with errorHandling set to retryOnError and retryType set to auto. The default is 60.

Argument type: String

retryType

(Optional) <auto|manual>

Specifies the type of retry when a process step or task fails. This can be used only for a task with errorHandling set to retryOnError. The default is auto.

Argument type: RetryType

rollingDeployEnabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 the pipeline runs the rolling deployment.

Argument type: Boolean

rollingDeployManualStepAssignees

(Optional) A list of assignees who receive the notification when the rolling deploy iteration is completed.

Argument type: Collection

rollingDeployManualStepCondition

(Optional) The Run if condition (run condition) on the manual step that was created during the rolling deployment.

Argument type: NotificationType

rollingDeployPhases

(Optional) One or more rolling deploy phases to be used in the rolling deployment.

Argument type: Collection

skippable

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, the task can be skipped in the pipeline.

Argument type: Boolean

snapshotName

(Optional) Name of the snapshot associated with the application.

When advancedMode is set to true or 1, advanced mode is enabled so that all validations for the applicationName, environmentName, processName, or snapshotName will be skipped. These objects can be represented using the " $[] " notation and later expanded at the pipeline runtime. For example, when advancedMode is enabled, the system does not validate that the environment exists or whether it is mapped to an application.

Argument type: String

stageName

(Optional) Name of the stage to which the task belongs.

Argument Type: String

startTime

(Optional) The time to begin invoking this task.

The time is formatted hh:mm using the 24-hours clock (for example, 17:00).

Argument Type: String

subapplication

(Optional) Name of the application that owns the subprocess.

Argument Type: String

subpluginKey

(Optional) If this argument references a procedure, the name of the pluginKey for the procedure

subprocedure

(Optional) Name of the subprocedure when a procedure is referenced.

Argument Type: String

subprocess

(Optional) Name of the CloudBees CD process.

Argument Type: String

subproject

(Optional) Name of the project in which the procedure runs.

Argument Type: String

subworkflowDefinition

(Optional) Name of the workflow definition in which the workflow definition is referenced.

Argument Type: String

subworkflowStartingState

(Optional) Name of the starting state in the specified workflow definition.

Argument Type: String

taskProcessType

(Optional) The type of the process that the task can invoke.

Argument Type: TaskProcessType

taskType

(Optional) The type of the task. One of: [APPROVAL|CI_JOB|COMMAND|CONDITIONAL|DEPLOYER|GROUP|MANUAL|PIPELINE|PLUGIN|PROCEDURE|PROCESS|RELEASE|UTILITY|WORKFLOW].

Argument Type: TaskType

tierResourceCounts

(Optional) The resource count for each resource template tier.

Argument Type: Map

useApproverAcl

(Optional) < Boolean flag0|1|true|false >

Used for manual stage tasks (see ). When this argument is set to true or 1, use approver’s permissions for further pipeline execution.

Argument type: Boolean

workspaceName

(Optional) The name of the workspace.

Argument Type: String

Positional arguments

projectName, taskName

Response

None or a status OK message.

ec-perl

syntax: $<object>->modifyTask(<projectName>, <taskName>, {<optionals>});

Example

To rename a task:

$ec->modifyTask("Default", "Save results", {newName => "Save output"});

To rename a task and make it the first task in a stage:

$ec->modifyTask("Default", "Enter user name and password", {firstTask => true, newName => "Enter credentials"});

To create a task with Run if and Wait until conditions:

$ec->modifyTask("Default", "Save output", {condition => true, precondition => "Enter credentials"});

ectool

syntax: ectool modifyTask <projectName> <taskName> [optionals]

Example

To rename a task:

ectool modifyTask "Default" "Save results" --newName "Save output"

To rename a task and make it the first task in a stage:

ectool modifyTask "Default" "Enter user name and password" --firstTask true --newName "Enter credentials"

To create a task with Run if and Wait until condition:

removeDeployerApplication

Removes a Deployer application for a Release.

You must specify the projectName and applicationName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

applicationProjectName

(Optional) Name of the project containing specified application. If it is not specified, the default is the Release project name.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument type: String

Positional arguments

projectName, applicationName

Response

Removes a Deployer application and its details.

ec-perl

syntax: $<object>->removeDeployerApplication(<projectName>, <applicationName>, {<optionals>});

Example

$ec->removeDeployerApplication("Default", "Verify versions", {applicationProjectName => "Software tools"});

ectool

syntax: ectool removeDeployerApplication <projectName> <applicationName> [optionals]

Example

ectool removeDeployerApplication "Default" "Verify versions" --applicationProjectName "Software tools"

removeDeployerConfiguration

Removes a Deployer configuration associated with a Deployer application.

You must specify the projectName, applicationName, and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

stageName

Name of the stage of a pipeline attached to a release if specified.

Argument Type: String

applicationProjectName

(Optional) Name of the project containing the application. If this argument is not specified, the default is the Release project name.

Argument Type: String

releaseName

(Optional) Name of the release.

Argument Type: String

Positional arguments

projectName, applicationName, stageName

Response

Removes the Deployer configuration and its details.

ec-perl

syntax: $<object>->removeDeployerConfiguration(<projectName>, <applicationName>, <stageName>,{<optionals>});

Example

$ec->removeDeployerConfiguration("Default", "Shopping Cart", "QA", {applicationProjectName => "Online store"});

ectool

syntax: ectool removeDeployerConfiguration <projectName> <applicationName> <stageName> [optionals]

Example

ectool removeDeployerConfiguration "Default" "Shopping Cart" "QA" --applicationProjectName "Online store"

removeTaskGroup

Removes a task group (but does not delete the tasks). The location of the ungrouped tasks will be the same as the location of the group task.

You must specify the projectName argument.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument Type: GateType

groupName

(Optional) Name of the group task.

Argument Type: String

pipelineName

(Optional) Name of the pipeline.

Argument type: String

releaseName

(Optional) Name of the release.

Argument Type: String

stageName

(Optional) Name of the stage to which the task belongs.

Argument Type: String

Positional arguments

projectName

Response

Removes the task group.

ec-perl

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

Example

$ec->removeTaskGroup("GroupTask2" {gateType => PRE});

ectool

syntax: ectool removeTaskGroup <projectName> [optionals]

Example

ectool removeTaskGroup "GroupTask2" --gateType PRE

restartPipelineRun

Restarts a pipeline run from the last failure point. Before restarting the pipeline run, update the task definition and fix issues causing the task to fail.

  • If specified pipeline configures the disableRestart flag to true or 1, it cannot be restarted.

  • If the pipeline configures the disableMultipleActiveRuns flag to true or 1, only one active run of this pipeline is allowed at a time and attempts to restart this one results in an exception. However, the user is able to restart the current pipeline from a stage or task.

Arguments Descriptions

actualparameter

(Optional) The list of actual parameters.

Argument Type: Map

comment

(Optional) Comment provided while restarting a pipeline run that completed with an error.

Argument Type: String

flowRuntimeId

(Optional) ID of the flow runtime to restart.

Argument Type: UUID

flowRuntimeName

(Optional) Name of the flow runtime to restart.

Argument Type: String

gateType

(Optional) The gate of the stage containing the task from which to restart the pipeline. Valid values are PRE and POST.

Argument Type: GateType

projectName

(Optional) Name of the project to which the pipeline belongs.

Argument Type: String

skipCurrent

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1, skip the current task or stage and restart the run from the following task or stage. A zero value causes pipeline to restart a current task or stage.

Where the current task or stage context is:

  • Full qualified with stageName and taskName arguments.

  • Task specified with taskName argument in current stage.

  • First task in specified stageName.

  • Current task and stage where pipeline stopped.

Argument Type: Boolean

stageName

(Optional) The name of the stage from which to start, or in the context of a restarted task, the stage containing the task from which to start.

Argument Type: String

taskName

(Optional) The name of the high-level task in the active (in case of a running pipeline) or last completed (in case of failed pipeline) stage.

Argument Type: String

Positional arguments

None.

Response

None or a status OK message.

ec-perl

syntax: $<object>->restartPipelineRun( {<optionals>});

$ec->restartPipelineRun({comment => "Restarting pipeline..."});

ectool

syntax: ectool restartPipelineRun --comment "Restarting pipeline…​"

retryTask

Retries a pipeline task. Applies only to waiting for manual retry tasks. It can be any pipeline task (excluding MANUAL, APPROVAL, GROUP, and DEPLOYER tasks) or an application deployment that is a part of a deployer task. In the last case, a subapplication (and a subproject by Perforce) should be provided.

You must specify the flowRuntimeId, stageName, and taskName arguments.

Arguments Descriptions

flowRuntimeId

ID of the flow runtime.

Argument Type: UUID

stageName

(Optional) Name of the stage to which the task belongs.

Argument Type: String

taskName

Name of the task.

Argument Type: String

action

(Optional) <fail|rerun|skip>

Action to execute: rerun, skip, or fail the task. The default is rerun.

Argument type: RetryTaskAction

comment

(Optional) Comment provided while retrying an action on the manual process step, manual task, or gate task.

Argument Type: String

gateType

(Optional) Type of the gate. Valid values are PRE and POST.

Argument type: GateType

subapplication

(Optional) Name of the subapplication for application deployment.

Argument Type: String

subproject

(Optional) Name of the project that contains the subapplication by Perforce. The default is equal to the project name of the flow runtime.

Argument Type: String

Positional arguments

flowRuntimeId, stageName, taskName

Response

None or a status OK message.

ec-perl

syntax: $<object>->retryTask(<flowRuntimeID>, <stageName>, <taskName>, {<optionals>});

$ec->retryTask("4fa765dd-73f1-11e3-b67e-b0a420524153", "Final Deploy", "Confirm version", {comment => "Task to confirm version for final deployment"});

ectool

syntax: ectool retryTask 4fa765dd-73f1-11e3-b67e-b0a420524153 "Final Deploy" "Confirm version" --comment "Task to confirm version for final deployment"

runPipeline

Runs the specified pipeline. If the pipeline configures disableMultipleActiveRuns= true, only one active run of this pipeline is allowed at a time and attempts to start more than one results in an exception.

You must specify the projectName and pipelineName arguments.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

pipelineName

Name of the pipeline that must be unique among all projects.

Argument Type: String

actualParameters

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

Argument Type: Map

credentials

(Optional) The credentials to be used in the task.

Argument type: Collection

priority

(Optional) Priority of jobs launched by the workflow.

Argument Type: JobPriority

releaseName

Name of the release.

Argument Type: String

scheduleName

(Optional) Name for the schedule for environment reservations that must be unique among all schedules for the project.

Argument Type: String

stagesToRun

(Optional) One or more stages to run in a pipeline.

Argument Type: Collection

startingStage

(Optional) Name of the starting stage.

Argument Type: String

webhookData

(Internal use, only) Free-form string containing information from a webhook callback. This argument is populated internally by webhook aware plugins, such as ECSCM.

Argument Type: String

Positional arguments

projectName, pipelineName

Response

Returns the flowRuntimeId object.

ec-perl

syntax: $<object>->runPipeline(<projectName>, <pipelineName>, {<optionals>});

Example

$ec->runPipeline("Default", "Web Site Update", {startingStage => "Green"});

ectool

syntax: ectool runPipeline <projectName> <pipelineName> [optionals]

Example

ectool runPipeline "Default" "Web Site Update" --startingStage "Green"

runFutureTask

Allow for task execution in future states or gates that have not started to run yet. Only the specified task is run; execution does not continue to following tasks and stages. When pipeline run execution reaches a task which has already run, pre-run task is skipped. If the task is still running then the pipeline execution waits for it to complete and then continues on to the following tasks.

A task can be pre-run if:

  • It is configured to run out of order. See allowOutOfOrderRun option to createTask and modifyTask .

  • All pre-conditions and run conditions, on both the task itself and a stage/gate containing the task, must evaluate to true.

  • No pending runtime wait dependencies on the task itself or stage/gate containing the task.

  • For stages: it is not excluded from the run.

  • The planned start date requirement for stage/gate and task is met (if configured with wait for start date).

Error handling on the specified task has no impact on its pre-run execution: the task runs and stops regardless of success or failure. However, when the regular execution reaches a pre-run task that has failed and has error handling defined as:

  • Stop on error —Pipeline execution stops.

  • Continue on error —Pipeline execution continues to the next task.

  • Retry —Task is retried.

Arguments Descriptions

flowRuntimeId

ID of the flow runtime containing the task to pre-run.

Argument Type: UUID

stageName

Name of the stage in which taskName resides.

Argument Type: String

taskName

Name of the task to pre-run.

Argument Type: String

gateType

(Optional) Type of the gate when taskName is a gate rule. Valid values are PRE and POST.

Argument type: GateType

Positional arguments

`flowRuntimeId stageName taskName `

Response

If successful, null is returned.

If task has not been configured for out-of-order execution:

[CantRunFutureTask]: Out of order run is not allowed for a task 'deploy' in stage 'PROD'

ec-perl

syntax: $<object>->runFutureTask(<flowRuntimeId>, <stageName>, <taskName>, {<gateType>});

Example

$ec->runFutureTask("c4721f69-7372-11e9-885c-0050568f29b0", "j-stage-2", "manualTask");

ectool

syntax: ectool runFutureTask <flowRuntimeId>, <stageName>, <taskName>, {←-gateType>}

Example

ectool runFutureTask c4721f69-7372-11e9-885c-0050568f29b0 j-stage-2 manualTask

setPipelineRunName

Rename a running pipeline.

Arguments Descriptions

newName

The new name for the flow runtime object.

Argument Type: Map

flowRuntimeId

(Optional) The primary key of the completed flow runtime object.

Argument Type: String

Positional arguments

<newName>

Response

None or a status OK message.

ec-perl

syntax: $<object>->setPipelineRunName(newName {<optionals>});

$ec->setPipelineRunName(newName => "NewPipelineName");

ectool

syntax: ectool setPipelineRunName NewPipelineName

startRelease

Starts a Release. If the release pipeline configures disableMultipleActiveRuns= true, only one active run of this release pipeline is allowed at a time and attempts to start more than one results in an exception.

You must specify the projectName and the releaseName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

releaseName

Name of the release.

Argument Type: String

priority

(Optional) The priority of jobs launched by the release.

Argument Type: JobPriority

stagesToRun

(Optional) One or more stages to run in a pipeline.

Argument Type: Collection

startingStage

(Optional) The name of the starting stage.

Argument type: String

webhookData

(Internal use, only) Free-form string containing information from a webhook callback. This argument is populated internally by webhook aware plugins, such as ECSCM.

Argument Type: String

Positional arguments

projectName, releaseName

Response

None or a status OK message.

ec-perl

syntax: $<object>->startRelease(<projectName>, <releaseName>, {<optionals>});

Example

$ec->startRelease("Default", "Production", {startingStage => "Checkout" });

ectool

syntax: ectool startRelease <projectName> <releaseName> [optionals]

Example

ectool startRelease "Default" "Production" --startingStage "Checkout"

validateDeployer

Validates the Deployer configuration.

You must specify the projectName, applicationName, and stageName.

Arguments Descriptions

projectName

Name of the project that must be unique among all projects.

Argument Type: String

applicationName

Name of the application.

Argument Type: String

stageName

Name of the stage of a pipeline attached to a release if specified.

Argument Type: String

actualParameters

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

Argument Type: Map

applicationProjectName

(Optional) The name of the project containing the application. If this argument is not specified, the default is the release project name.

Argument Type: String

environmentName

(Optional) Name of the environment to create from a template.

Argument Type: String

environmentProjectName

(Optional) Name of the project containing specified environment or environment template. If this argument is not specified, the default is the release project name.

Argument Type: String

environmentTemplateName

(Optional) Name of the environment template to use.

Argument Type: String

environmentTemplateProjectName

(Optional) Name of the project containing specified environment template. If this argument is not specified, the default is the environment project name.

Argument Type: String

insertRollingDeployManualStep

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 a manual step needs to be added after each phase or batch is run.

Argument type: Boolean

releaseName

(Optional) Name of the release.

Argument Type: String

rollingDeployEnabled

(Optional) < Boolean flag0|1|true|false >

When this argument is set to true or 1 the pipeline runs the rolling deployment.

Argument type: Boolean

rollingDeployManualStepAssignees

(Optional) A list of assignees who receive the notification when the rolling deploy iteration is completed.

Argument type: Collection

rollingDeployManualStepCondition

(Optional) The Run if condition (run condition) on the manual step that was created during the rolling deployment.

Argument type: NotificationType

rollingDeployPhases

(Optional) One or more rolling deploy phases to be used in the rolling deployment.

Argument type: Collection

validationType

(Optional) The type of validation to perform:

  • APPROVER for approver

  • PARAM for parameter

  • ENV for environment

  • ALL for all validations

The default is ALL.

Argument Type: DeployerValidationType

Positional arguments

projectName, applicationName, stageName

Response

None or a status OK message.

ec-perl

syntax: $<object>->validateDeployer(<projectName>, <applicationName>, <stageName>, {<optionals>});

Example

$ec->validateDeployer("Default", "Make WAR file", "Checkin", {releaseName => "Web Site"});

ectool

syntax: ectool validateDeployer <projectName> <applicationName> <stageName> [optionals]

Example

ectool validateDeployer "Default" "Make WAR file" "Checkin" --releaseName "Web Site"

waitForFlowRuntime

Waits until the pipeline specified by the flow runtime ID is completed or the timeout expires.

You must specify the flowRuntimeId.

This command works only with ec-perl.

Arguments Descriptions

flowRuntimeId

The ID of the flow runtime for the pipeline.

Argument type: UUID

timeout

(Optional) The number of seconds to wait before giving up on a request.

The default is 60 seconds.

Argument type: Integer

Positional arguments

flowRuntimeId

Response

Returns the flowRuntimeId.

ec-perl

syntax: $<object>->waitForFlowRuntime(<flowRuntimeId>, {<optionals>});

Example

$ec->waitForFlowRuntime("4fa765dd-73f1-11e3-b67e-b0a420524153", {timeout => 30});