Process Step

Several of these API commands have context-type optional arguments. For example, a step command might reference either a procedure or a component.

completeManualProcessStep

Completes a manual process step.

Required arguments

jobStepId

This is the unique CloudBees CD/RO -generated identifier (a UUID) for a job step that is assigned automatically when the job step is created. The system also accepts a job step name assigned to the job step by its name template.

UUID

Optional arguments

action

The type of action to be taken on the manual process step. Valid values are completed and failed. Additionally, skip is an available value if the manual step is configured with ` allowSkip=true`. If this manual process step is configured with disableFailure=1, then this argument is ignored—the step always completes with success.

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

ManualProcessStepStatus

actualParameters

The parameters passed as arguments to the process step.

Map

comment

Evidence provided while taking an action on the manual process step, which is not interpreted by CloudBees CD/RO .

String

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->completeManualProcessStep(<jobStepId>, {<optionals>});

Example:

To approve the manual process step:

$ec->completeManualProcessStep("4fa765dd-73f1-11e3-b67e-b0a420524153", {action => completed, comment => "Success"});

To reject the manual process step:

$ec->completeManualProcessStep("4fa765de-73f1-11e3-b67e-b0a420524153", {action => failed, comment => "Try again"});

ectool

Syntax:

ectool completeManualProcessStep <jobStepId>  [optionals]

Example:

To approve the manual process step:

ectool completeManualProcessStep "4fa765dd-73f1-11e3-b67e-b0a420524153" --action completed --comment "Success"

To reject the manual process step:

ectool completeManualProcessStep "4fa765de-73f1-11e3-b67e-b0a420524153" --action failed --comment "Try again"

createProcessStep

Creates a new process step.

Required arguments

projectName

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

Argument Type: String

String

processName

Name of the process.

String

processStepName

Name of the process step.

String

Optional arguments

actionLabelText

A JSON string used to assign custom label text to manual step actions. Use with manual steps.

{
   "completed":"<completedLabel>",
   "failed":"<failedLabel>",
   "skipped":"<skippedLabel>"
}

Where:

completedLabel —used for successful outcome; default label is Completed.

failedLabel —used for unsuccessful outcome; default label is Failed.

skippedLabel —used for task skipping; default label is Skip this step.

String

actualParameter

Actual parameters (<var1>=<val1> [<var2>=<val2> …) passed to an invoked subprocedure or process.

Map

allowSkip

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), this step can be skipped at runtime—only users specified in the approver list will be allowed to skip.

Boolean

afterProcessStep

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

String

applicationName

Name of the application containing the specified application process step ( processStepName ). When you want to create an application process step, specify the name of the application ( applicationName ) containing this process step. The application name must be unique among all projects.

String

applicationTierName

Application tier on which to run the step.

String

assignees

A list of assignees who receive the notification.

Collection

beforeProcessStep

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

String

componentApplicationName

Name of the application where the component ( componentName ) is located. When you want to create a component process step in a specific application, specify the component ( componentName ) and the application ( componentApplicationName ) where the component is located.

String

componentName

Name of the component containing the process step. When you want to create a component process step in a specific application, specify the component (componentName ) and application ( componentApplicationName ) where the component is located.

String

componentRollback

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), rollback will be performed only for the components that were not deployed successfully.

Boolean

credentialName

Name of the credential object.

String

dependencyJoinType

Join type for incoming dependencies.

ProcessDependencyJoinType

description

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

String

disableFailure

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), this step cannot be failed—it will always complete with success.

Boolean

errorHandling

Specifies error handling for this step.

ErrorHandling

includeCompParameterRef

True if the actual parameters should be generated from component properties. Works for artifact components only.

Boolean

instruction

Instruction associated with the manual process step.

String

notificationTemplate

Email notification template for process step.

String

processStepType

Defines type of the process step. For a component process, valid values are command, component, manual, none, plugin, procedure, and utility. For an application process, valid values are command, manual, none, plugin, procedure, process, rollback, and utility.

ProcessStepType

rollbackSnapshot

Name of the snapshot to be used for rollback.

String

rollbackType

The type of the rollback.Valid values are environment (rollback to the previous environment state) and snapshot (rollback to a user-specified snapshot).

RollbackProcessStepType

rollbackUndeployProcess

Name of the undeploy process to be used during rollback.

String

microserviceApplicationName

If specified, the name of the application that contains the microservice.

String

microserviceName

The name of the microservice, if the process is owned by a microservice.

String

smartRollback

< Boolean flag — 0|1|true|false > The smart deploy flag to be used during rollback is triggered. When this argument is set to true or 1, smart deploy is enabled during rollback.

Boolean

subcomponent

If referencing a component process, the name of the component.

String

subcomponentApplicationName

If referencing a component process, the name of the component application when it is not scoped to a project.

String

subcomponentProcess

If referencing a component process, the name of the component process.

String

subprocedure

If referencing a procedure, the name of the procedure.

String

subproject

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

String

subMicroserviceProcess

If referencing a microservice process, the name of the microservice process.

String

subMicroservice

If referencing a microservice process, the name of the microservice.

String

timeLimit

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

String

timeLimitUnits

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

TimeLimitUnits

workspaceName

Name of the workspace.

String

Response

Returns a process step element.

ec-perl

Syntax:

$<object>->createProcessStep(<projectName>, <processName>, <processStepName>, {<optionals>});

Example:

To create a component process step in a master component:

$ec->createProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file'});

To create a component process step in a specific application:

$ec->createProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file', componentApplicationName => 'Shopping Cart'});

To create an application process step:

$ec->createProcessStep('Default', 'Deploy', 'Check out', {applicationName => 'Shopping Cart'});

ectool

Syntax:

ectool createProcessStep <projectName> <processName> <processStepName> [optionals]

Example:

To create a component process step in a master component:

ectool createProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file'

To create a component process step in a specific application:

ectool createProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'

To create an application process step:

ectool createProcessStep  'Default' 'Deploy' 'Check out' --applicationName 'Shopping Cart'

deleteProcessStep

Deletes an application or component process step.

Required arguments

projectName

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

Argument Type: String

String

processName

Name of the process.

String

processStepName

Name of the process step.

String

Optional arguments

applicationName

Name of the application containing the specified application process step ( processStepName ). When you want to delete an application process step, specify the name of the application ( applicationName ) containing this process step. The application name must be unique among all projects.

String

componentApplicationName

Name of the application where the component ( componentName ) is located. When you want to delete a component process step in a specific application, specify the component ( componentName ) and the application ( componentApplicationName ) where the component is located.

String

componentName

Name of the component containing the process step. When you want to delete a component process step in a specific application, specify the component (componentName ) and application ( componentApplicationName ) where the component is located.

String

microserviceApplicationName

Name of the application to which the microservice process containing the step is scoped.

String

microserviceName

The name of the microservice, if the process is owned by a microservice.

String

Response

None or a status OK message.

ec-perl

Syntax:

$<object>->deleteProcessStep(<projectName>, <processName>, <processStepName>, {<optionals>});

Example:

To delete a component process step in a master component:

$ec->deleteProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file'});

To delete a component process step in a specific application:

$ec->deleteProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file', componentApplicationName => 'Shopping Cart'});

To delete an application process step:

$ec->deleteProcessStep('Default', 'Deploy', 'Check out', {applicationName => 'Shopping Cart'});

ectool

Syntax:

ectool deleteProcessStep <projectName> <processName> <processStepName> [optionals]

Example:

To delete a component process step in a master component:

ectool deleteProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file'

To delete a component process step in a specific application:

ectool deleteProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'

To delete an application process step:

ectool deleteProcessStep  'Default' 'Deploy' 'Check out' --applicationName 'Shopping Cart'

getProcessStep

Retrieves an application or component process step.

Required arguments

projectName

Name of the project. This name must be unique among all projects.Argument Type: String

String

processName

Name of the process.

String

processStepName

Name of the process step.

String

Optional arguments

applicationEntityRevisionId

Revision ID of the versioned object.

UUID

applicationName

Name of the application containing the specified application process step ( processStepName ). When you want to retrieve an application process step, specify the name of the application ( applicationName ) containing this process step. The application name must be unique among all projects.

String

componentApplicationName

Name of the application where the component ( componentName ) is located. When you want to retrieve a component process step in a specific application, specify the component ( componentName ) and the application ( componentApplicationName ) where the component is located.

String

componentName

Name of the component containing the process step. When you want to retrieve a component process step in a specific application, specify the component (componentName ) and application ( componentApplicationName ) where the component is located.

String

microserviceApplicationName

Name of the application to which the microservice process containing the step is scoped.

String

serviceEntityRevisionId

Revision ID of the versioned object.

UUID

microserviceName

The name of the microservice, if the process is owned by a microservice.

String

Response

Returns a process step element.

ec-perl

Syntax:

$<object>->getProcessStep(<projectName>, <processName>, <processStepName>, {<optionals>});

Example:

To retrieve a component process step in a master component:

$ec->getProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file'});

To retrieve a component process step in a specific application:

$ec->getProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file', componentApplicationName => 'Shopping Cart'});

To retrieve an application process step:

$ec->getProcessStep('Default', 'Deploy', 'Check out', {applicationName => 'Shopping Cart'});

ectool

Syntax:

ectool getProcessStep <projectName> <processName> <processStepName> [optionals]

Example:

To retrieve a component process step in a master component:

ectool getProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file'

To retrieve a component process step in a specific application:

ectool getProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'

To retrieve an application process step:

ectool getProcessStep  'Default' 'Deploy' 'Check out' --applicationName 'Shopping Cart'

getProcessSteps

Retrieves all the process steps in an application or component process.

Required arguments

projectName

Name of the project. This name must be unique among all projects.Argument Type: String

String

processName

Name of the process.

String

Optional arguments

applicationEntityRevisionId

Revision ID of the versioned project.

UUID

applicationName

Name of the application containing the application process steps. When you want to retrieve all the application process steps, specify the name of the application ( applicationName ) containing them. The application name must be unique among all projects.

String

componentApplicationName

Name of the application where the component ( componentName ) is located. When you want to retrieve all the component process steps in a specific application, specify the component ( componentName ) and application ( componentApplicationName ) where the component is located.

String

componentName

Name of the component containing the process step. When you want to retrieve all component process steps in a specific application, specify the component (componentName ) and application ( componentApplicationName ) where the component is located.

String

microserviceApplicationName

Name of the application to which the microservice process containing the step is scoped.

String

serviceEntityRevisionId

Revision ID of the versioned object.

UUID

microserviceName

The name of the microservice, if the process is owned by a microservice.

String

Response

Returns zero or more process step elements.

ec-perl

Syntax:

$<object>->getProcessSteps(<projectName>, <processName>, {<optionals>});

Example:

To retrieve all the component process steps in a master component:

$ec->getProcessSteps('Default', 'Deploy',  {componentName => 'WAR file'});

To retrieve all the component process steps in a specific application:

$ec->getProcessSteps('Default', 'Deploy',  {componentName => 'WAR file', componentApplicationName => 'Shopping Cart'});

To retrieve all the application process steps in an application:

$ec->getProcessSteps('Default', 'Deploy',  {applicationName => 'Shopping Cart'});

ectool

Syntax:

ectool getProcessSteps  <projectName> <processName> [optionals]

Example:

To retrieve all the component process steps in a master component:

ectool getProcessSteps 'Default' 'Deploy' --componentName 'WAR file'

To retrieve all the component process steps in a specific application:

ectool getProcessSteps 'Default' 'Deploy'  --componentName 'WAR file' --componentApplicationName 'Shopping Cart'

To retrieve all the application process steps in an application:

ectool getProcessSteps  'Default' 'Deploy' --applicationName 'Shopping Cart'

modifyProcessStep

Modifies an existing process step.

Required arguments

projectName

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

String

processName

Name of the process.

String

processStepName

Name of the process step.

String

Optional arguments

actionLabelText

A JSON string used to assign custom label text to manual step actions. Use with manual steps.

{
   "completed":"<completedLabel>",
   "failed":"<failedLabel>",
   "skipped":"<skippedLabel>"
}

Where:

completedLabel —used for successful outcome; default label is Completed.

failedLabel —used for unsuccessful outcome; default label is Failed.

skippedLabel —used for task skipping; default label is Skip this step.

String

actualParameter

Actual parameters passed to an invoked subprocedure or process.

Map

afterProcessStep

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

String

allowSkip

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), this step can be skipped at runtime—only users specified in the approver list will be allowed to skip.

Boolean

applicationName

Name of the application containing the specified application process step ( processStepName ). When you want to modify an application process step, specify the name of the application ( applicationName ) containing this process step. The application name must be unique among all projects.

String

applicationTierName

Name of the application tier on which to run the step.

String

assignees

A list of assignees who receive the notification.

Collection

beforeProcessStep

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

String

clearActualParameters

True if the step should remove all actual parameters.

Boolean

componentApplicationName

Name of the application where the component ( componentName ) is located. When you want to modify a component process step in a specific application, specify the component ( componentName ) and the application ( componentApplicationName ) where the component is located.

String

componentName

Name of the component containing the process step. When you want to modify a component process step in a specific application, specify the component (componentName ) and application ( componentApplicationName ) where the component is located.

String

componentRollback

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), rollback will be performed only for the components that were not deployed successfully.

Boolean

credentialName

Name of the credential object.

String

dependencyJoinType

Join type for incoming dependencies.

ProcessDependencyJoinType

description

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

String

disableFailure

< Boolean flag — 0|1|true|false > When set to 1 or true (enabled), this step cannot be failed—it will always complete with success.

Boolean

errorHandling

Specifies error handling for this step.

ErrorHandling

includeCompParameterRef

< Boolean flag — 0|1|true|false > Set this flag to "true" or "1" if the actual parameters should be generated from component properties. This works only for artifact components.

Boolean

instruction

Instruction associated with the manual process step.

String

newName

New name for an existing object that is being renamed.

String

notificationTemplate

Email notification template for process step.

String

processStepType

ProcessStepType

rollbackSnapshot

Name of the snapshot to be used for rollback.

String

rollbackType

The type of the rollback.

RollbackProcessStepType

rollbackUndeployProcess

Name of the undeploy process to be used during rollback.

String

microserviceApplicationName

Name of the application to which the microservice process containing the step is scoped.

String

microserviceName

The name of the microservice, if the process is owned by a microservice.

String

smartRollback

< Boolean flag — 0|1|true|false > The smart deploy flag to be used during rollback is triggered. When this argument is set to true or 1, smart deploy is enabled during rollback.

Boolean

subcomponent

If referencing a component process, the name of the component.

String

subcomponentApplicationName

If referencing a component process, the name of the component application (if it has not been scoped to a project).

String

subcomponentProcess

If referencing a component process, the name of the component process.

String

subprocedure

If referencing a procedure, the name of the procedure.

String

subproject

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

String

subServiceProcess

If referencing a microservice process, the name of the microservice process.

String

timeLimit

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

String

timeLimitUnits

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

TimeLimitUnits

workspaceName

Name of the workspace.

String

Response

Returns an updated process step element.

ec-perl

Syntax:

$<object>->modifyProcessStep(<projectName>, <processName>, <processStepName>, {<optionals>});

Example:

To modify a component process step in a master component:

$ec->modifyProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file', newName => 'Backup files'});

To modify a component process step in a specific application:

$ec->modifyProcessStep('Default', 'Deploy', 'Check out', {componentName => 'WAR file', componentApplicationName => 'Shopping Cart', newName => 'Backup files'});

To modify an application process step:

$ec->modifyProcessStep('Default', 'Deploy', 'Check out', {applicationName => 'Shopping Cart', newName => 'Backup files'});

ectool

Syntax:

ectool modifyProcessStep <projectName> <processName> <processStepName> [optionals]

Example:

To modify a component process step in a master component:

ectool modifyProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file' --newName 'Backup files'

To modify a component process step in a specific application:

ectool modifyProcessStep 'Default' 'Deploy' 'Check out' --componentName 'WAR file' --componentApplicationName 'Shopping Cart' --newName 'Backup files'

To modify an application process step:

ectool modifyProcessStep  'Default' 'Deploy' 'Check out' --applicationName 'Shopping Cart' --newName 'Backup files'