Using the Perl API
IntroductionAccess tokensACL managementApplication dependencyApplicationsApplication tier Artifact managementCatalogsChange historyCI build detailCI configurationCI jobsComponentsCredential managementCustom filtersDatabase configurationData retentionCloudBees AnalyticsDirectory provider managementDynamic environmentsEmail configuration managementEmail notifier managementEnvironmentEnvironment tierGateway and zone managementGet application environment inventoryInstalling or upgrading remote agentsJob managementMicroservicesObject tagsParameter managementPersonasPipelines and releasesPlugin managementPlugin configuration managementProcedure managementProcessProcess dependencyProcess stepProject managementProperty managementResource managementRolling deploySchedule managementService accounts for webhooksServer managementSingle sign on for SAMLSnapshotsTier mapTrigger managementUser and group managementUser profile email managementWait dependenciesWorkflow definition managementWorkflow managementWork itemsWorkspace managementMiscellaneous management
Perl API response and element glossary
IntroductionExamplesTroubleshooting
IntroductionaccesstokenaclaclentryactualparameterapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcatalogitemruncibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitionstringresulttagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Appliciation and component process

9 minute readReference

createProcess

Creates a new process for an application or component.

Argument Description

projectName

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

Argument Type: String

processName

Name of the process.

Argument Type: String

applicationName

Name of the application containing processName.

Argument Type: String

Use for components

componentApplicationName

Name of the application containing componentName.

Argument Type: String

componentName

Name of the component.

Use for microservices

microserviceApplicationName

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

Argument Type: String

microserviceName

The name of the microservice.

Argument Type: String

General parameters

credentialName

(Optional) Name of a credential to attach to this process.

Argument Type: String

description

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

Argument Type: String

exclusiveEnvironment

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

When this argument is set to true or 1, exclusive access to the environment is required. Applicable only to application and microservice processes.

Argument Type: Boolean

processType

(Optional) Defines the type of action performed by the process. Valid value is DEPLOY.

Argument Type: Process Type

serviceApplicationName

(deprecated) No longer supported.

Argument Type: String

serviceName

(deprecated) No longer supported.

Argument Type: String

timeLimit

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

Argument Type: String

timeLimitUnits

(Optional) Units for the step- time limit: seconds, minutes, or hours.

Argument Type: TimeLimitUnits

workingDirectory

(Optional) Name of the working directory for this process.

Argument Type: String

workspaceName

(Optional) Name of the default workspace for this process.

Argument Type: String

Positional arguments

projectName, processName

Response

Returns a process component element.

ec-perl

Syntax:

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

Example:

To create a component process in a master component:

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

To create a component process in a specific application:

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

To create an application process:

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

To create an microservice process:

$ec->createProcess('Default', 'Deploy',  {microserviceName => 'myapp-ms', microserviceApplicationName => 'myapp'});
▼

ectool

Syntax:

ectool createProcess <projectName> <processName> [optionals]
▼

Example:

To create a component process in a master component:

ectool createProcess 'Default' 'Deploy'  --componentName 'WAR file'
▼

To create a component process in a specific application:

ectool createProcess 'Default' 'Deploy' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'
▼

To create an application process:

ectool createProcess  'Default' 'Deploy'  --applicationName 'Shopping Cart'
▼

To create an microservice process:

ectool createProcess  'Default' 'Deploy'  --microserviceName 'myapp-ms' --microserviceApplicationName 'myapp'
▼

deleteProcess

Deletes an application or component process.

Argument Description

projectName

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

Argument Type: String

processName

Name of the process.

Argument Type: String

applicationName

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

Argument Type: String

Use for components.

componentApplicationName

Name of the application where componentName is located.

Argument Type: String

componentName

Name of the component. Use to delete a component process in a specific application.

Argument Type: String

Use for microservices.

microserviceApplicationName

(Optional) Name of the microservice application.

Argument Type: String

microserviceName

(Optional) Name of the component.

Argument Type: String

General parameters

serviceApplicationName

(deprecated) No longer supported.

Argument Type: String

serviceName

(deprecated) No longer supported.

Argument Type: String

Positional arguments

projectName, processName

Response

None or a status OK message.

ec-perl

Syntax:

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

Example:

To delete a component process in a master component:

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

To create a component process in a specific application:

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

To create an application process:

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

ectool

Syntax:

ectool deleteProcess <projectName> <processName> [optionals]
▼

Example:

To delete a component process in a master component:

ectool deleteProcess 'Default' 'Deploy'  --componentName 'WAR file'
▼

To create a component process in a specific application:

ectool deleteProcess 'Default' 'Deploy' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'
▼

To create an application process:

ectool deleteProcess  'Default' 'Deploy'  --applicationName 'Shopping Cart'
▼

getProcess

Retrieves an application or component process.

Name Description

projectName

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

Argument Type: String

processName

Name of the process.

Argument Type: String

applicationEntityRevisionId

(Optional) The revision ID of the versioned project.

Argument Type: UUID

applicationName

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

Argument Type: String

componentApplicationName

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

Argument Type: String

componentName

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

Argument Type: String

microserviceApplicationName

(Optional) Name of the application (not the service) to which this application is scoped.

Argument Type: String

microserviceName

(Optional) The name of the service, if the process is owned by a service.

Argument Type: String

Positional arguments

projectName, processName

Response

Returns the specified process object.

ec-perl

Syntax:

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

Example:

To retrieve a component process in a master component:

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

To retrieve a component process in a specific application:

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

To retrieve an application process:

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

ectool

Syntax:

ectool getProcess <projectName> <processName> [optionals]
▼

Example:

To retrieve a component process in a master component:

ectool getProcess 'Default' 'Deploy'  --componentName 'WAR file'
▼

To retrieve a component process in a specific application:

ectool getProcess 'Default' 'Deploy' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'
▼

To retrieve an application process:

ectool getProcess  'Default' 'Deploy'  --applicationName 'Shopping Cart'
▼

getProcesses

Retrieves all processes in an application or component.

Argument Description

projectName

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

Argument Type: String

applicationEntityRevisionId

(Optional) The revision ID of the versioned project.

Argument Type: UUID

applicationName

(Optional) Name of the application where the processes are located. When you want to retrieve all the application processes, specify the application ( applicationName ). The application name must be unique among all projects.

Argument Type: String

componentApplicationName

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

Argument Type: String

componentName

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

Argument Type: String

microserviceApplicationName

(Optional) Name of the application to which the microservice containing the process is scoped.

Argument Type: String

microserviceName

(Optional) The name of the service, if the process is owned by a service.

Argument Type: String

Positional arguments

projectName

Response

Returns the specified process element.

ec-perl

Syntax:

$<object>>->getProcesses(<projectName>, {<optionals>});
▼

Example:

To retrieve all the component process in a master component:

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

To retrieve all the component processes in a specific application:

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

To retrieve all the application processes in the specified application:

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

ectool

Syntax:

ectool getProcesses <projectName> [optionals]
▼

Example:

To retrieve a component process in a master component:

ectool getProcesses 'Default' --componentName 'WAR file'
▼

To retrieve a component process in a specific application:

ectool getProcesses 'Default' --componentName 'WAR file' --componentApplicationName 'Shopping Cart'
▼

To retrieve an application process in a specific application:

ectool getProcesses  'Default' --applicationName 'Shopping Cart'
▼

modifyProcess

Modifies an existing process.

Argument Description

projectName

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

Argument Type: String

processName

Name of the process.

Argument Type: String

applicationName

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

Argument Type: String

componentApplicationName

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

Argument Type: String

componentName

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

Argument Type: String

credentialName

(Optional) Name of a credential to attach to this process.

Argument Type: String

description

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

Argument Type: String

exclusiveEnvironment

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

When this argument is set to true or 1, exclusive access to the environment is required. Applicable only to application and microservice processes.

Argument Type: Boolean

newName

(Optional) New name for an existing object that is being renamed.

Argument Type: String

processType

(Optional) Defines the type of action performed by the process. Valid value is DEPLOY.

Argument Type: String

microserviceApplicationName

(Optional) If specified, the microservice is scoped to this application.

Argument Type: String

microserviceName

(Optional) The name of the service, if the process is owned by a service.

Argument Type: String

timeLimit

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

Argument Type: String

timeLimitUnits

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

Argument Type: TimeLimitUnits

workspaceName

(Optional) Name of the default workspace for this process.

Argument Type: String

Positional arguments

projectName, processName

Response

Returns an updated process object.

ec-perl

Syntax:

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

Example:

To modify a component process in a master component:

$ec->modifyProcess('Default', 'Deploy',  {componentName => 'WAR file', newName => 'Daily Update'});
▼

To modify a component process in a specific application:

$ec->modifyProcess('Default', 'Deploy',  {componentName => 'WAR file', componentApplicationName => 'Shopping Cart', newName => 'Daily Update'});
▼

To modify an application process:

$ec->modifyProcess('Default', 'Deploy',  {applicationName => 'Shopping Cart', newName => 'Daily Update'});
▼

ectool

Syntax:

ectool modifyProcess <projectName> <processName> [optionals]
▼

Example:

To modify a component process in a master component:

ectool modifyProcess 'Default' 'Deploy'  --componentName 'WAR file' --newName 'Daily Update'
▼

To modify a component process in a specific application:

ectool modifyProcess 'Default' 'Deploy' --componentName 'WAR file' --componentApplicationName 'Shopping Cart' --newName 'Daily Update'
▼

To modify an application process:

ectool modifyProcess  'Default' 'Deploy'  --applicationName 'Shopping Cart' --newName 'Daily Update'
▼

runProcess

Runs the specified process. For microservice applications, used to deploy a microservice to a Kubernetes cluster.

Argument Description

projectName

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

Argument Type: String

processName

Name of the application process.

Argument Type: String

applicationName

Name of the application that owns the process; it must be unique among all applications in the project.

Argument Type: String

Parameters below are for traditional applications, only.

actualParameter

(Optional) Parameters passed as arguments to the process.

Argument Type: Map

credentials

(Optional) Credentials to use in the job.

Argument Type: Collection

destinationProject

(Optional) Project that will own the job.

Argument Type: String

environmentName

(Optional) Name of the environment.

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.

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

environmentTemplateTierMapName

(Optional) Name of the environment template tier map.

Argument Type: String

keepOnError

(Optional) Set this flag to "true" to keep the environment when an error occurs . The keepOnError value is < Boolean flag - 0|1|true|false >. The default is false or 0

Argument Type: Boolean

pollInterval

(Optional) This argument requires setting a value in seconds to determine how often ectool queries the CloudBees CD/RO server for job status, but this is not an indefinite activity–set the timeout value to extend the pollInterval for longer than 60 seconds if needed. If this option is not specified, runProcedure returns immediately. If it is specified, runProcedure waits until the job completes.

Argument Type: Integer

priority

(Optional) Priority of the job.

Argument Type: JobPriority

rollingDeployEnabled

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "1" or "true" to enable rolling deploy.

Argument Type: Boolean

rollingDeployManualStepAssignees

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

Argument Type: Collection

rollingDeployManualStep

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" or "1" to wait for human intervention when the rolling deployment phase is completed.

rollingDeployManualStepCondition

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

Argument Type: NotificationType

rollingDeployPhases

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

Argument Type: Collection

scheduleName

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

Argument Type: String

smartDeploy

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "true" to override the actual parameters.

Argument Type: Boolean

snapshotName

(Optional) Name for the snapshot that must be unique among all snapshots for the project.

Argument Type: String

stageArtifacts

(Optional) < Boolean flag - 0|1|true|false > Set this flag to "1" or "true" to stage all the artifacts being deployed as part of the application process. The default is "true".

tierMapName

(Optional) Name of the tier map used to determine where to run the process.

Argument Type: String

tierResourceCounts

(Optional) Resource count for each resource template tier.

Argument Type: Map

timeout

(Optional) This argument requires a value set in seconds . If pollInterva l is specified, this timeout causes runProcedure to stop waiting for the job to complete. It does not stop the job itself. If pollInterval is used and timeout is not used, pollInterval will timeout in 60 seconds.

Argument Type: Integer

validate

(Optional) Validates that the application process, tier map, and environment are well-defined and valid before the running the application process. The value is < Boolean flag - 0|1|true|false >. The default is true.

Argument Type: Boolean

Positional arguments

projectName, applicationName, processName

Response

Returns new job ID.

If the --pollInterval option is provided, CloudBees CD/RO waits until the job completes up to a maximum of --timeout seconds (if also provided).

ec-perl

Syntax:

$<object>>->runProcess(<projectName>, <applicationName>, <processName>,{<optionals>});
▼

Example:

$ec->runProcess('Default', 'Deploy', 'Check out', {tierMapName => 'QA test'});
▼

ectool

Syntax:

ectool runProcess <projectName> <applicationName> <processName> [optionals]
▼

Example:

ectool runProcess 'Default' 'Deploy' 'Check out' --tierMapName 'QA test'
▼
Procedure management
Process dependency