Pipeline

26 minute readReference

abortAllPipelineRuns

Aborts all pipeline runs associated with a release.

Arguments

Argument Name Type Description

projectName

String

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

force

Boolean

If true running tasks are force aborted.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool abortAllPipelineRuns projectName [optionals]

abortPipelineRun

Aborts a pipeline run.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

The ID of the flow runtime.

flowRuntimeName

String

The name of the flow runtime.

force

Boolean

If true running tasks are force aborted.

projectName

String

The name of the project.

Positional arguments

None.

Usage

ec-perl

$cmdr->abortPipelineRun({<optionals>});

ectool

ectool abortPipelineRun [optionals]

attachPipelineRun

Adds a pipeline run to a release with a status of running or planning; pipeline runs cannot be attached to completed releases.

Arguments

Argument Name Type Description

projectName

String

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

flowRuntimeId

UUID

The ID of the pipeline run to attach.

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool attachPipelineRun projectName [optionals]

completeManualTask

Completes the manual task.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime.

stageName

String

(Required) The name of the stage.

taskName

String

(Required) The name of the task.

action

ManualProcessStepStatus

The type of action to be taken on the manual process step or manual task or gate task.

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

evidence

String

Evidence provided while taking an action on the manual process step or manual task or gate task.

gateType

GateType

The type of the gate.

Positional arguments

flowRuntimeId, stageName, taskName

Usage

ec-perl

$cmdr->completeManualTask(<flowRuntimeId>, <stageName>, <taskName>, {<optionals>});

ectool

ectool completeManualTask flowRuntimeId stageName taskName [optionals]

createGate

Creates a new gate for a stage.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

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

gateType

GateType

(Required) The type of the gate.

condition

String

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

description

String

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

pipelineName

String

The name of the pipeline.

precondition

String

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

releaseName

String

The name of the release.

Positional arguments

projectName, stageName, gateType

Usage

ec-perl

$cmdr->createGate(<projectName>, <stageName>, <gateType>, {<optionals>});

ectool

ectool createGate projectName stageName gateType [optionals]

createNote

Creates a new note.

Arguments

Argument Name Type Description

note

String

(Required) This represents the notes provided about the entity.

noteName

String

The name of the note.

projectName

String

ProjectName of the entity that owns the note.

releaseName

String

Name of the release.

Positional arguments

note

Usage

ec-perl

$cmdr->createNote(<note>, {<optionals>});

ectool

ectool createNote note [optionals]

createPipeline

Creates a new pipeline for a project.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

(Required) The name of the pipeline.

assigneesForSkipStage

Collection

A list of users who can skip stages at runtime.

description

String

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

disableMultipleActiveRuns

Boolean

Boolean flag showing if option to run multiple pipelines simultaneously is disabled.

disableRestart

Boolean

True to disable restart the pipeline.

enabled

Boolean

True to enable the pipeline.

overrideWorkspace

Boolean

If true and workspaceName is not null, then all tasks use pipeline’s workspace.

pipelineRunNameTemplate

String

Template used to determine the default name for pipelines on startup.

releaseName

String

The name of the release.

skipStageMode

StageSkipMode

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

type

PipelineType

Type of pipeline.

workspaceName

String

The name of the default workspace for this pipeline.

Positional arguments

projectName, pipelineName

Usage

ec-perl

$cmdr->createPipeline(<projectName>, <pipelineName>, {<optionals>});

ectool

ectool createPipeline projectName pipelineName [optionals]

createStage

Creates a new stage in a pipeline for a project.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

(Required) The name of the stage.

afterStage

String

If specified, the stage will be placed after the named stage.

beforeStage

String

If specified, the stage will be placed before the named stage.

colorCode

String

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

completed

Boolean

Set true to complete and false to incomplete a stage with manual completion type. A stage with auto completion type ignores this argument.

completionType

StageCompletionType

The stage completion type: auto (be default) or manual.

condition

String

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

description

String

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

duration

String

Duration in minutes for which the stage or task should relative to plannedStartDate.

incompletePostStages

Boolean

If True, then in case of specified stage incompletion, all post stages are not completed too.

parallelToPrevious

Boolean

If TRUE, the flow state will be run in parallel to the previous flow state.

pipelineName

String

The name of the pipeline.

plannedEndDate

String

The date when this stage or task is expected to end.

plannedStartDate

String

The date when this stage or task is expected to start.

precondition

String

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

releaseName

String

The name of the release.

resourceName

String

The name of the default resource for this stage.

timeZone

String

The time zone to use when interpreting times.

waitForPlannedStartDate

Boolean

True to enable waiting for planned start date.

Positional arguments

projectName, stageName

Usage

ec-perl

$cmdr->createStage(<projectName>, <stageName>, {<optionals>});

ectool

ectool createStage projectName stageName [optionals]

createTask

Creates a new task for a task container.

Arguments

Argument Name Type Description

projectName

String

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

taskName

String

(Required) The name of the task.

actionLabelText

String

The JSON derived action label text.

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

advancedMode

Boolean

True to enable advanced mode so as to templatize snapshotName.

afterLastRetry

AfterLastRetryErrorHandling

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

afterTask

String

If specified, the task will be placed after the named task.

allowOutOfOrderRun

Boolean

If True, allow to run a task out of order.

allowSkip

Boolean

When enabled, manual task or gate rule can be skipped.

alwaysRun

Boolean

True means this task will run even if preceding tasks fail in a way that aborts the pipeline.

applicationName

String

The name of the application used in sub task.

applicationProjectName

String

Name for the project to which the application belongs to.

applicationVersion

String

Application version to be deployed by a sub task.

approvers

Collection

A list of task approvers who receive the notification.

artifacts

String

If specified, the task will be placed before the named task.

beforeTask

String

If specified, the task will be placed before the named task.

ciConfigurationName

String

The CI configuration name.

ciControllerFolder

String

Path to the folder on the CI controller referenced by the CloudBees Operation Center that contains the specified CI controller. Must be in format folder1/folder2/folder3/…​ .

ciControllerName

String

DEPRECATED: Name of the CI controller. Deprecated in favor of ciEndpoint argument.

ciEndpoint

String

Endpoint value configured for CI controller.

ciJobBranchName

String

Name of the CI Job Branch.

ciJobFolder

String

Path to the folder on the CI server referenced by the CI configuration that contains the specified CI job. Must be in format folder1/folder2/folder3/…​ .

ciJobName

String

Name of the CI job.

command

String

The command to run.

condition

String

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

customLabel

String

Custom display name for sub pipelines or releases.

deployerExpression

String

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

deployerRunType

TaskRunType

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

description

String

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

disableFailure

Boolean

True means a manual task cannot be failed.

duration

String

Duration in minutes for which the stage or task should relative to plannedStartDate.

emailConfigName

String

The name of email configuration.

enabled

Boolean

True to enable the task.

environmentName

String

Environment name to create from template.

environmentProjectName

String

Name for the project to which the environment or environment template belongs to.

environmentTemplateName

String

Environment template name.

environmentTemplateProjectName

String

Name for the project to which the environment template belongs to.

errorHandling

FlowStateErrorHandling

Specifies error handling for this task.

firstTask

Boolean

True to make a task first in a stage.

gateCondition

String

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

gateType

GateType

The type of the gate.

groupName

String

The name of the group of task.

groupRunType

TaskRunType

The type of the sub task run for a group task. If serial then all tasks are run in serial, otherwise - in parallel (by default).

insertRollingDeployManualStep

Boolean

True to indicate a manual step needs to be injected after each phase or batch.

instruction

String

Instruction associated with the task.

keepOnError

Boolean

True to keep environment on error (default is false).

notificationEnabled

Boolean

True means this email notification is enabled, false otherwise.

notificationTemplate

String

String containing email formatting instructions for generating notifications.

outOfOrderRunAssignees

Collection

A list of users who can run a task out of order.

parallelToPrevious

Boolean

If TRUE, the flow state will be run in parallel to the previous flow state.

pipelineName

String

The name of the pipeline.

plannedEndDate

String

The date when this stage or task is expected to end.

plannedStartDate

String

The date when this stage or task is expected to start.

postp

String

The postprocessor for the task.

precondition

String

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

releaseName

String

The name of the release.

requiredApprovalsCount

String

The number of users from a group that should approve the task before it’s considered as finally approved.

resourceName

String

The name of the default resource for this task.

retryCount

String

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

retryInterval

String

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

retryType

RetryType

Type of retry when process step or task fails. Is one of auto or manual.

rollingDeployEnabled

Boolean

Perform rolling deployment.

rollingDeployManualStepAssignees

Collection

A list of assignees who receive the notification when rolling deploy iteration completes.

rollingDeployManualStepCondition

NotificationType

Defines run condition on manual step created during rolling deployment.

rollingDeployPhases

Collection

One or more rolling deploy phases to be used for deployment.

shell

String

shellToUse

skippable

Boolean

True if a task is skippable.

snapshotName

String

Name of the snapshot associated with the application.

stageName

String

Name of the stage to which this task belongs to.

stageSummaryParameters

String

JSON representation of stage summary parameters and labels.

stagesToRun

Collection

One or more stages to run in a pipeline.

startTime

String

The time of day to begin invoking this task (24-hour clock, for example, 17:00).

startingStage

String

The name of the starting stage.

subErrorHandling

SubErrorHandling

The impact of invoking pipeline run when sub-pipeline fails.

subTaskType

String

The type of the sub task.

subapplication

String

The name of the application that owns the subprocess.

subpipeline

String

If referencing a pipeline, the name of the pipeline.

subpluginKey

String

If referencing a procedure, the name of the procedure’s pluginKey.

subprocedure

String

If referencing a procedure, the name of the procedure.

subprocess

String

The name of the process.

subproject

String

If referencing a procedure, the name of the procedure’s project.

subrelease

String

If referencing a release, the name of the release.

subreleasePipeline

String

The name of the pipeline to be used when attaching to the release instantiate from a release task.

subreleasePipelineProject

String

The name of the project which contains the pipeline to the release instantiate from a release task.

subreleaseSuffix

String

The suffix to be used when creating release.

subworkflowDefinition

String

If referencing a workflow definition, the name of the workflow definition.

subworkflowStartingState

String

The name of the starting state in the specified workflow definition.

taskProcessType

TaskProcessType

The type of the process a task can invoke.

taskType

TaskType

The type of the task.

tierResourceCounts

Map

Resource count per resource template tier.

timeZone

String

The time zone to use when interpreting times.

triggerType

SubpipelineRunTriggerType

The type of trigger when invoking a sub-pipeline.

useApproverAcl

Boolean

True if after approve the authentication context of approving user should be added to the session.

waitForPlannedStartDate

Boolean

True to enable waiting for planned start date.

workspaceName

String

The name of the workspace.

Positional arguments

projectName, taskName

Usage

ec-perl

$cmdr->createTask(<projectName>, <taskName>, {<optionals>});

ectool

ectool createTask projectName taskName [optionals]

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 or to add them into an existing group.

Arguments

Argument Name Type Description

projectName

String

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

gateType

GateType

The type of the gate.

groupName

String

The name of the group task.

groupRunType

TaskRunType

The type of the sub task run for a group task. If serial then all tasks are run in serial, otherwise - in parallel (by default).

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

stageName

String

Name of the stage to which this task belongs to.

taskNames

Collection

Tasks to put into the group.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool createTaskGroup projectName [optionals]

deleteGate

Deletes a gate in a stage.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

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

gateType

GateType

(Required) The type of the gate.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName, stageName, gateType

Usage

ec-perl

$cmdr->deleteGate(<projectName>, <stageName>, <gateType>, {<optionals>});

ectool

ectool deleteGate projectName stageName gateType [optionals]

deleteNote

Deletes a note associated with an entity.

Arguments

Argument Name Type Description

noteName

String

(Required) The name of the note.

projectName

String

ProjectName of the entity that owns the note.

releaseName

String

Name of the release.

Positional arguments

noteName

Usage

ec-perl

$cmdr->deleteNote(<noteName>, {<optionals>});

ectool

ectool deleteNote noteName [optionals]

deletePipeline

Deletes a pipeline in a project.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

(Required) The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName, pipelineName

Usage

ec-perl

$cmdr->deletePipeline(<projectName>, <pipelineName>, {<optionals>});

ectool

ectool deletePipeline projectName pipelineName [optionals]

deletePipelineRun

Deletes a pipeline runtime.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

The ID of the flow runtime.

flowRuntimeName

String

The name of the flow runtime.

projectName

String

The name of the project.

Positional arguments

None.

Usage

ec-perl

$cmdr->deletePipelineRun({<optionals>});

ectool

ectool deletePipelineRun [optionals]

deleteStage

Deletes a stage in a project.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

(Required) The name of the stage.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName, stageName

Usage

ec-perl

$cmdr->deleteStage(<projectName>, <stageName>, {<optionals>});

ectool

ectool deleteStage projectName stageName [optionals]

deleteTask

Deletes a task in a task container.

Arguments

Argument Name Type Description

projectName

String

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

taskName

String

(Required) The name of the task.

gateType

GateType

The type of the gate.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

stageName

String

Name of the stage to which this task belongs to.

Positional arguments

projectName, taskName

Usage

ec-perl

$cmdr->deleteTask(<projectName>, <taskName>, {<optionals>});

ectool

ectool deleteTask projectName taskName [optionals]

detachPipelineRun

Detaches a pipeline run from the specified release.

Arguments

Argument Name Type Description

projectName

String

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

flowRuntimeId

UUID

The ID of the pipeline run to attach.

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool detachPipelineRun projectName [optionals]

getAllWaitingTasks

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

Arguments

Argument Name Type Description

projectName

String

(Required) Name for the project; must be unique among all projects.

flowRuntimeId

UUID

The ID of the flow runtime.

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool getAllWaitingTasks projectName [optionals]

getAttachedPipelineRuns

Fetches all attached runs for the specified release.

Arguments

Argument Name Type Description

projectName

String

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

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool getAttachedPipelineRuns projectName [optionals]

getGate

Retrieves a gate by its stage name and gate type.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

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

gateType

GateType

(Required) The type of the gate.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName, stageName, gateType

Usage

ec-perl

$cmdr->getGate(<projectName>, <stageName>, <gateType>, {<optionals>});

ectool

ectool getGate projectName stageName gateType [optionals]

getNote

Retrieves a note associated with an entity.

Arguments

Argument Name Type Description

noteName

String

(Required) The name of the note.

projectName

String

ProjectName of the entity that owns the note.

releaseName

String

Name of the release.

Positional arguments

noteName

Usage

ec-perl

$cmdr->getNote(<noteName>, {<optionals>});

ectool

ectool getNote noteName [optionals]

getNotes

Retrieves all notes associated with an entity.

Arguments

Argument Name Type Description

projectName

String

ProjectName of the entity that owns the note.

releaseName

String

Name of the release.

Positional arguments

None.

Usage

ec-perl

$cmdr->getNotes({<optionals>});

ectool

ectool getNotes [optionals]

getPipeline

Retrieves a pipeline by its name.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

(Required) The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName, pipelineName

Usage

ec-perl

$cmdr->getPipeline(<projectName>, <pipelineName>, {<optionals>});

ectool

ectool getPipeline projectName pipelineName [optionals]

getPipelineRunAuditReport

Retrieves a detailed data set for the specified pipeline run to be used in audit reports.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

The ID of the pipeline or release run to generate the audit report.

Positional arguments

None.

Usage

ec-perl

$cmdr->getPipelineRunAuditReport({<optionals>});

ectool

ectool getPipelineRunAuditReport [optionals]

getPipelineRuntimeDetails

Retrieves pipeline runtime details.

Arguments

Argument Name Type Description

flowRuntimeIds

Collection

List of pipeline flowruntime IDs of interest.

Positional arguments

None.

Usage

ec-perl

$cmdr->getPipelineRuntimeDetails({<optionals>});

ectool

ectool getPipelineRuntimeDetails [optionals]

getPipelineRuntimes

Retrieves pipeline runs.

Arguments

Argument Name Type Description

filters

Collection

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

firstResult

Integer

Result pagination: the first row to return.

flowRuntimeId

UUID

The ID of the flow runtime.

flowRuntimeName

String

The name of the flow runtime.

maxResults

Integer

Result pagination: the number of rows to return.

pipelineName

String

The name of the pipeline.

projectName

String

The name of the project.

releaseId

UUID

The ID of the release.

releaseName

String

The name of the release.

sortKey

String

How to sort the results.

sortOrder

SortOrder

Specifies the order to sort the results.

viewName

String

The name of the view.

Positional arguments

None.

Usage

ec-perl

$cmdr->getPipelineRuntimes({<optionals>});

ectool

ectool getPipelineRuntimes [optionals]

getPipelines

Retrieves all the pipelines.

Arguments

Argument Name Type Description

projectName

String

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

Positional arguments

projectName

Usage

ec-perl

$cmdr->getPipelines(<projectName>);

ectool

ectool getPipelines projectName

getPipelineStageRuntimeTasks

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

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime.

firstResult

Integer

Result pagination: the first row to return.

maxResults

Integer

Result pagination: the number of rows to return.

sortKey

String

How to sort the results.

sortOrder

SortOrder

Specifies the order to sort the results.

stageName

String

The name of the stage.

stageRunNumber

Integer

The stage run number.

Positional arguments

flowRuntimeId

Usage

ec-perl

$cmdr->getPipelineStageRuntimeTasks(<flowRuntimeId>, {<optionals>});

ectool

ectool getPipelineStageRuntimeTasks flowRuntimeId [optionals]

getReleaseInventory

Retrieves the artifact inventory created in a release.

Arguments

Argument Name Type Description

projectName

String

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

releaseName

String

(Required) The name of the release.

Positional arguments

projectName, releaseName

Usage

ec-perl

$cmdr->getReleaseInventory(<projectName>, <releaseName>);

ectool

ectool getReleaseInventory projectName releaseName

getRunHierarchy

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

Arguments

Argument Name Type Description

filters

Collection

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

flowRuntimeId

UUID

The ID of the flow runtime.

mode

PortfolioViewMode

The mode of portfolio view.

pipelineName

String

The name of the pipeline.

projectName

String

The name of the project.

releaseName

String

The name of the release.

Positional arguments

None.

Usage

ec-perl

$cmdr->getRunHierarchy({<optionals>});

ectool

ectool getRunHierarchy [optionals]

getStage

Retrieves a stage by its name.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

(Required) The name of the stage.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

timeZone

String

The time zone to use when interpreting times.

Positional arguments

projectName, stageName

Usage

ec-perl

$cmdr->getStage(<projectName>, <stageName>, {<optionals>});

ectool

ectool getStage projectName stageName [optionals]

getStages

Retrieves all the stages for a pipeline.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool getStages projectName [optionals]

getTask

Retrieves a task by its name.

Arguments

Argument Name Type Description

projectName

String

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

taskName

String

(Required) The name of the task.

gateType

GateType

The type of the gate.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

stageName

String

Name of the stage to which this task belongs to.

timeZone

String

The time zone to use when interpreting times.

validate

Boolean

If passed 1, then all validations check if the definition is complete and valid.

Positional arguments

projectName, taskName

Usage

ec-perl

$cmdr->getTask(<projectName>, <taskName>, {<optionals>});

ectool

ectool getTask projectName taskName [optionals]

getTasks

Retrieves all tasks.

Arguments

Argument Name Type Description

projectName

String

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

gateType

GateType

The type of the gate.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

stageName

String

Name of the stage to which this task belongs to.

validate

Boolean

If passed 1, then all validations check if the definition is complete and valid.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool getTasks projectName [optionals]

getWaitingTasks

Retrieves a list of all stage tasks that are waiting on a manual approval or waiting for manual retry tasks in a pipeline run view.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime.

stageName

String

(Required) The name of the stage.

taskName

String

The name of the deployer or group task.

Positional arguments

flowRuntimeId, stageName

Usage

ec-perl

$cmdr->getWaitingTasks(<flowRuntimeId>, <stageName>, {<optionals>});

ectool

ectool getWaitingTasks flowRuntimeId stageName [optionals]

modifyGate

Modifies an existing gate.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

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

gateType

GateType

(Required) The type of the gate.

condition

String

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

description

String

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

pipelineName

String

The name of the pipeline.

precondition

String

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

releaseName

String

The name of the release.

Positional arguments

projectName, stageName, gateType

Usage

ec-perl

$cmdr->modifyGate(<projectName>, <stageName>, <gateType>, {<optionals>});

ectool

ectool modifyGate projectName stageName gateType [optionals]

modifyNote

Modifies a note associated with an entity.

Arguments

Argument Name Type Description

noteName

String

(Required) The name of the note.

newName

String

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

note

String

This represents the notes provided about the entity.

projectName

String

ProjectName of the entity that owns the note.

releaseName

String

Name of the release.

Positional arguments

noteName

Usage

ec-perl

$cmdr->modifyNote(<noteName>, {<optionals>});

ectool

ectool modifyNote noteName [optionals]

modifyPipeline

Modifies an existing pipeline.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

(Required) The name of the pipeline.

assigneesForSkipStage

Collection

A list of users who can skip stages at runtime.

description

String

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

disableMultipleActiveRuns

Boolean

Boolean flag showing if option to run multiple pipelines simultaneously is disabled.

disableRestart

Boolean

True to disable restart the pipeline.

enabled

Boolean

True to enable the pipeline.

newName

String

New name for an existing object that is being renamed.

overrideWorkspace

Boolean

If true and workspaceName is not null, then all tasks use pipeline’s workspace.

pipelineRunNameTemplate

String

Template used to determine the default name for pipelines on startup.

releaseName

String

The name of the release.

skipStageMode

StageSkipMode

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

type

PipelineType

Type of pipeline.

workspaceName

String

The name of the default workspace for this pipeline.

Positional arguments

projectName, pipelineName

Usage

ec-perl

$cmdr->modifyPipeline(<projectName>, <pipelineName>, {<optionals>});

ectool

ectool modifyPipeline projectName pipelineName [optionals]

modifyStage

Modifies an existing stage.

Arguments

Argument Name Type Description

projectName

String

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

stageName

String

(Required) The name of the stage.

afterStage

String

If specified, the stage will be placed after the named stage.

beforeStage

String

If specified, the stage will be placed before the named stage.

colorCode

String

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

completed

Boolean

Set true to complete and false to incomplete a stage with manual completion type. A stage with auto completion type ignores this argument.

completionType

StageCompletionType

The stage completion type: auto (be default) or manual.

condition

String

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

description

String

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

duration

String

Duration in minutes for which the stage or task should relative to plannedStartDate.

incompletePostStages

Boolean

If True, then in case of specified stage incompletion, all post stages are not completed too.

newName

String

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

parallelToPrevious

Boolean

If TRUE, the flow state will be run in parallel to the previous flow state.

pipelineName

String

The name of the pipeline.

plannedEndDate

String

The date when this stage or task is expected to end.

plannedStartDate

String

The date when this stage or task is expected to start.

precondition

String

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

releaseName

String

The name of the release.

resourceName

String

The name of the default resource for this stage.

timeZone

String

The time zone to use when interpreting times.

waitForPlannedStartDate

Boolean

True to enable waiting for planned start date.

Positional arguments

projectName, stageName

Usage

ec-perl

$cmdr->modifyStage(<projectName>, <stageName>, {<optionals>});

ectool

ectool modifyStage projectName stageName [optionals]

modifyTask

Modifies an existing task.

Arguments

Argument Name Type Description

projectName

String

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

taskName

String

(Required) The name of the task.

actionLabelText

String

The JSON derived action label text.

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

advancedMode

Boolean

True to enable advanced mode so as to templatize snapshotName.

afterLastRetry

AfterLastRetryErrorHandling

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

afterTask

String

If specified, the task will be placed after the named task.

allowOutOfOrderRun

Boolean

If True, allow to run a task out of order.

allowSkip

Boolean

When enabled, manual task or gate rule can be skipped.

alwaysRun

Boolean

True means this task will run even if preceding tasks fail in a way that aborts the pipeline.

applicationName

String

The name of the application used in sub task.

applicationProjectName

String

Name for the project to which the application belongs to.

applicationVersion

String

Application version to be deployed by a sub task.

approvers

Collection

A list of task approvers who receive the notification.

artifacts

String

If specified, the task will be placed before the named task.

beforeTask

String

If specified, the task will be placed before the named task.

ciConfigurationName

String

The CI configuration name.

ciControllerFolder

String

Path to the folder on the CI controller referenced by the CloudBees Operation Center that contains the specified CI controller. Must be in format folder1/folder2/folder3/…​ .

ciControllerName

String

DEPRECATED: Name of the CI controller. Deprecated in favor of ciEndpoint argument.

ciEndpoint

String

Endpoint value configured for CI controller.

ciJobBranchName

String

Name of the CI Job Branch.

ciJobFolder

String

Path to the folder on the CI server referenced by the CI configuration that contains the specified CI job. Must be in format folder1/folder2/folder3/…​ .

ciJobName

String

Name of the CI job.

clearActualParameters

Boolean

True if the task should remove all actual parameters.

clearOutOfOrderRunAssignees

Boolean

True if the task should clean up all outOfOrderRunAssignees.

clearStageSummaryParameters

Boolean

True if the task should remove all stage summary parameters.

command

String

The command to run.

condition

String

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

customLabel

String

Custom display name for sub pipelines or releases.

deployerExpression

String

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

deployerRunType

TaskRunType

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

description

String

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

disableFailure

Boolean

True means a manual task cannot be failed.

duration

String

Duration in minutes for which the stage or task should relative to plannedStartDate.

emailConfigName

String

The name of email configuration.

enabled

Boolean

True to enable the task.

environmentName

String

Environment name to create from template.

environmentProjectName

String

Name for the project to which the environment or environment template belongs to.

environmentTemplateName

String

Environment template name.

environmentTemplateProjectName

String

Name for the project to which the environment template belongs to.

errorHandling

FlowStateErrorHandling

Specifies error handling for this task.

firstTask

Boolean

True to make a task first in a stage.

gateCondition

String

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

gateType

GateType

The type of the gate.

groupName

String

The name of the group of task.

groupRunType

TaskRunType

The type of the sub task run for a group task. If serial then all tasks are run in serial, otherwise - in parallel (by default).

insertRollingDeployManualStep

Boolean

True to indicate a manual step needs to be injected after each phase or batch.

instruction

String

Instruction associated with the task.

keepOnError

Boolean

True to keep environment on error (default is false).

newName

String

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

notificationEnabled

Boolean

True means this email notification is enabled, false otherwise.

notificationTemplate

String

String containing email formatting instructions for generating notifications.

outOfOrderRunAssignees

Collection

A list of users who can run a task out of order.

parallelToPrevious

Boolean

If TRUE, the flow state will be run in parallel to the previous flow state.

pipelineName

String

The name of the pipeline.

plannedEndDate

String

The date when this stage or task is expected to end.

plannedStartDate

String

The date when this stage or task is expected to start.

postp

String

The postprocessor for the task.

precondition

String

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

releaseName

String

The name of the release.

requiredApprovalsCount

String

The number of users from a group that should approve the task before it’s considered as finally approved.

resourceName

String

The name of the default resource for this task.

retryCount

String

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

retryInterval

String

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

retryType

RetryType

Type of retry when process step or task fails. Is one of auto or manual.

rollingDeployEnabled

Boolean

Perform rolling deployment.

rollingDeployManualStepAssignees

Collection

A list of assignees who receive the notification when rolling deploy iteration completes.

rollingDeployManualStepCondition

NotificationType

Defines run condition on manual step created during rolling deployment.

rollingDeployPhases

Collection

One or more rolling deploy phases to be used for deployment.

shell

String

The shell to use.

skippable

Boolean

True if a task is skippable.

snapshotName

String

Name of the snapshot associated with the application.

stageName

String

Name of the stage to which this task belongs to.

stageSummaryParameters

String

JSON representation of stage summary parameters and labels.

stagesToRun

Collection

One or more stages to run in a pipeline.

startTime

String

The time of day to begin invoking this task (24-hour clock, for example, 17:00).

startingStage

String

The name of the starting stage.

subErrorHandling

SubErrorHandling

The impact of invoking pipeline run when sub-pipeline fails.

subTaskType

String

The type of the sub task.

subapplication

String

The name of the application that owns the subprocess.

subpipeline

String

If referencing a pipeline, the name of the pipeline.

subpluginKey

String

If referencing a procedure, the name of the procedure’s pluginKey.

subprocedure

String

If referencing a procedure, the name of the procedure.

subprocess

String

The name of the process.

subproject

String

If referencing a procedure, the name of the procedure’s project.

subrelease

String

If referencing a release, the name of the release.

subreleasePipeline

String

The name of the pipeline to be used when attaching to the release instantiate from a release task.

subreleasePipelineProject

String

The name of the project which contains the pipeline to the release instantiate from a release task.

subreleaseSuffix

String

The suffix to be used when creating release.

subworkflowDefinition

String

If referencing a workflow definition, the name of the workflow definition.

subworkflowStartingState

String

The name of the starting state in the specified workflow definition.

taskProcessType

TaskProcessType

The type of the process a task can invoke.

taskType

TaskType

The type of the task.

tierResourceCounts

Map

Resource count per resource template tier.

timeZone

String

The time zone to use when interpreting times.

triggerType

SubpipelineRunTriggerType

The type of trigger when invoking a sub-pipeline.

useApproverAcl

Boolean

True if after approve the authentication context of approving user should be added to the session.

waitForPlannedStartDate

Boolean

True to enable waiting for planned start date.

workspaceName

String

The name of the workspace.

Positional arguments

projectName, taskName

Usage

ec-perl

$cmdr->modifyTask(<projectName>, <taskName>, {<optionals>});

ectool

ectool modifyTask projectName taskName [optionals]

pausePipelineRun

Pause the pipeline run.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the pipeline run to pause/resume.

Positional arguments

flowRuntimeId

Usage

ec-perl

$cmdr->pausePipelineRun(<flowRuntimeId>);

ectool

ectool pausePipelineRun flowRuntimeId

removeTaskGroup

Removes a task group, but does not delete the tasks. The location of the ungrouped tasks is the same as the location of the group task.

Arguments

Argument Name Type Description

projectName

String

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

gateType

GateType

The type of the gate.

groupName

String

The name of the group task.

pipelineName

String

The name of the pipeline.

releaseName

String

The name of the release.

stageName

String

Name of the stage to which this task belongs to.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool removeTaskGroup projectName [optionals]

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 the 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 it results in an exception. However, the user is able to restart the current pipeline from a stage or task.

Arguments

Argument Name Type Description

actualParameters

Map

The list of actual parameters.

comment

String

Comment provided while restarting pipeline run which has completed with error.

flowRuntimeId

UUID

The ID of the flow runtime.

flowRuntimeName

String

The name of the flow runtime.

gateType

GateType

The type of the gate.

projectName

String

The name of the project.

stageName

String

The name of a stage from which to restart a pipeline.

taskName

String

The name of a high-level task in the last active stage from which to restart a pipeline.

Positional arguments

None.

Usage

ec-perl

$cmdr->restartPipelineRun({<optionals>});

ectool

ectool restartPipelineRun [optionals]

resumePipelineRun

Resume the pipeline run.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the pipeline run to pause/resume.

Positional arguments

flowRuntimeId

Usage

ec-perl

$cmdr->resumePipelineRun(<flowRuntimeId>);

ectool

ectool resumePipelineRun flowRuntimeId

retryTask

Retries a pipeline task. This only applies to tasks that are waiting for a manual retry. 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. For application deployments, a subapplication (and a subproject by Perforce) should be provided.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime.

stageName

String

(Required) The name of the stage.

taskName

String

(Required) The name of the task.

action

RetryTaskAction

Action to execute: rerun (default), skip or fail the task.

comment

String

Comment provided while retry an action on the manual process step or manual task or gate task.

gateType

GateType

The type of the gate.

subapplication

String

The name of the sub application.

subproject

String

The name of the project that contains the sub application.

Positional arguments

flowRuntimeId, stageName, taskName

Usage

ec-perl

$cmdr->retryTask(<flowRuntimeId>, <stageName>, <taskName>, {<optionals>});

ectool

ectool retryTask flowRuntimeId stageName taskName [optionals]

runFutureTask

Allows 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 the following tasks and stages. When pipeline run execution reaches a task which has already run, the pre-run task is skipped. If the task is still running, 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.

  • 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

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime.

stageName

String

(Required) The name of the stage.

taskName

String

(Required) The name of the task.

gateType

GateType

The type of the gate.

Positional arguments

flowRuntimeId, stageName, taskName

Usage

ec-perl

$cmdr->runFutureTask(<flowRuntimeId>, <stageName>, <taskName>, {<optionals>});

ectool

ectool runFutureTask flowRuntimeId stageName taskName [optionals]

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.

Arguments

Argument Name Type Description

projectName

String

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

pipelineName

String

(Required) The name of the pipeline.

actualParameters

Map

The list of actual parameters.

credentialReferenceParameters

Map

List of credential parameters with references to existing credentials as parameter values. If the parameter value is a property reference then the credential would be resolved at runtime.

credentials

Collection

Credentials to be used in the state.

parsedWebhookData

String

JSON with parsed webhook data to be set on a pipeline/release/procedure run.

priority

JobPriority

The priority of jobs launched by the pipeline.

releaseName

String

The name of the release.

scheduleName

String

Name for the schedule; must be unique among all schedules for the project.

stagesToRun

Collection

One or more stages to run in a pipeline.

startingStage

String

The name of the starting stage.

startingTask

String

The name of the starting task.

startingTaskStage

String

The name of the stage containing starting task.

webhookData

String

The webhook data to be set on the pipeline/release/procedure run.

webhookHeaders

String

The webhook headers in JSON format to be set on the pipeline/release/procedure run.

Positional arguments

projectName, pipelineName

Usage

ec-perl

$cmdr->runPipeline(<projectName>, <pipelineName>, {<optionals>});

ectool

ectool runPipeline projectName pipelineName [optionals]

setPipelineRunName

Renames a running pipeline.

Arguments

Argument Name Type Description

newName

String

(Required) The new name for the flow runtime.

flowRuntimeId

String

The primary key of the completed flowRuntime.

Positional arguments

newName

Usage

ec-perl

$cmdr->setPipelineRunName(<newName>, {<optionals>});

ectool

ectool setPipelineRunName newName [optionals]

waitForFlowRuntime

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

This command is only supported with ec-perl.

Arguments

Argument Name Type Description

flowRuntimeId

UUID

(Required) The ID of the flow runtime for the pipeline.

timeout

Integer

The number of seconds to wait before giving up on a request. The default is 60 seconds.

Positional arguments

flowRuntimeId

Usage

ec-perl

$cmdr->waitForFlowRuntime(<flowRuntimeId>, {<optionals>});