API error messages
Introduction
IntroductionAccess tokenACLApplication dependencyApplicationApplication tierArchive connectorArtifactCatalogChange historyCI buildCI build detailCI configurationCI eventCI jobClusterComponentsCredentialCredential providerCustom filterDashboardDashboard columnDatabase configurationData retention policyDeployer applicationDevOps Insight data sourceDirectory providerDynamic environmentEmail configurationEmail notifierEnvironmentEnvironment tierGatewayGroupInstalling or upgrading remote agentsJobKerberos keytabMicroserviceMicroservice mappingMiscellaneousObjectObject tagsParameterPersonaPipelinePluginPlugin configurationPlugin catalogProcedureProcessProcess dependencyProcess stepProjectPropertyReleaseReportReporting filterReport object associationReport object attributeReport object typeResourceRolling deployScheduleSCM syncServerServer settings categoryService accounts for webhooksSessionSingle sign-on for OpenID ConnectSingle sign-on for SAMLSnapshotsTier mapTriggerUserUser emailUtility resourceWait dependencyWebhook resultWidgetWidget filter overrideWorkflowWorkflow definitionWork itemsWorkspaceZone
Perl API response and element glossary
Introduction
Examples
Troubleshooting
IntroductionaccesstokenaclaclentryactualparameterapplicationapplicationdependencyapplicationtierarchiveconnectorartifactartifactversioncatalogcatalogitemcibuildcibuilddetailciconfigurationcieventclustercomponentcredentialcredentialproviderdashboarddashboardcolumndataretentionpolicydeployerapplicationdeployerconfigurationdeploymenthistoryitemdevopsinsightdatasourcedirectoryprovideremailconfigemailnotifierentitychangeenvironmentenvironmentinventoryitemenvironmenttemplateenvironmenttemplatetierenvironmenttemplatetiermapenvironmenttemplatetiermappingenvironmenttierenvtempltierresourcetemplmappingeventsubscriptionflowruntimeformaloutputparameterformalparametergategatewaygrouphookjobjobstepkerberoskeytablicensemicroservicemicroservicemappingnoteobjectopenidconnectconfigurationoutputparameterpersonapersonacategorypersonapagepipelinepluginplugincatalogpluginconfigurationprocedureprocedurestepprocessprocessdependencyprocessstepprojectpropertyreleasereportreportingfilterreportobjectassociationreportobjectattributereportobjecttyperepositoryreservationresourceresourcepoolresourcetemplateresourceusageretrievedartifactsrollingdeployphaserundiscoverysamlidentityprovidersamlserviceproviderschedulescmsyncsearchfilterserverserversettingserversettingcategoryserviceaccountsessionsnapshotstagestatestatedefinitionstringresulttagtasktiermaptiermappingtransitiontransitiondefinitiontriggertriggererrordetailuseraccesstokenuseruseremailutilityresourcewaitdependencywebhookresultwidgetwidgetfilteroverrideworkflowworkflowdefinitionworkitemworkspacezoneArgument models

Resource

7 minute readReference

addResourcesToPool

Adds resources to the specified resource pool (a named group of resources).

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

resourceNames

Collection

List of resources to add/remove from the pool.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->addResourcesToPool(<resourcePoolName>, {<optionals>});
▼

ectool

ectool addResourcesToPool resourcePoolName [optionals]
▼

addResourceToEnvironmentTier

Adds a resource to the specified environment tier.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

projectName

String

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

environmentName

String

(Required) The name of the environment.

environmentTierName

String

(Required) Name for the environment tier; must be unique among all tiers for the environment.

rollingDeployPhaseName

String

Name for the rolling deploy phase to be associated with the resource.

Positional arguments

resourceName, projectName, environmentName, environmentTierName

Usage

ec-perl

$cmdr->addResourceToEnvironmentTier(<resourceName>, <projectName>, <environmentName>, <environmentTierName>, {<optionals>});
▼

ectool

ectool addResourceToEnvironmentTier resourceName projectName environmentName environmentTierName [optionals]
▼

createResource

Creates a new resource. For a proxy resource, the proxyHostName and proxyPort arguments refer to the proxying CloudBees CD/RO agent. The hostName and port arguments refer to the proxy target.

Resource objects inherit their privileges from Resources privileges. To create a resource, you must have modify privileges on Resources, and you must have Modify privileges on the zone.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

artifactCacheDirectory

String

Artifact cache directory for this resource.

block

Boolean

True to block on the agent ping before returning.

description

String

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

hostName

String

The domain name or IP address of the server machine corresponding to this resource.

hostType

String

The type of the host.

pools

String

DEPRECATED: A list of arbitrary names separated by spaces, indicating the pools with which this resource is associated.

port

Integer

Port number to use when connecting to the agent for this resource; defaults to server default.

proxyCustomization

String

Proxy specific customization data; defaults to none.

proxyHostName

String

The domain name or IP address of the proxy agent machine corresponding to this resource.

proxyPort

Integer

Port number to use when connecting to the proxy agent for this resource; defaults to server default.

proxyProtocol

String

The protocol to use when proxying to this resource; defaults to none.

repositoryNames

String

A newline delimited list of repositories to retrieve artifacts from.

resourceDisabled

Boolean

True means this resource will not be allocated to job steps, regardless of its step limit.

resourcePools

String

A list of arbitrary names separated by comma, indicating the pools with which this resource is associated.

shell

String

Name of the shell program that will execute the command and postprocessor for the step.

stepLimit

Integer

The maximum number of steps that may execute simultaneously using this resource.

trusted

Boolean

True means the agent can speak to all other trusted agents in its zone. An untrusted agent can only speak to gateway agents.

useSSL

Boolean

True means SSL is used for communication.

workspaceName

String

The name of the workspace.

zoneName

String

Name for the zone; must be unique among all zones.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->createResource(<resourceName>, {<optionals>});
▼

ectool

ectool createResource resourceName [optionals]
▼

createResourcePool

Creates a new pool for resources.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

autoDelete

Boolean

If true, the pool is deleted when the last resource is deleted.

description

String

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

orderingFilter

String

JavaScript fragment that returns custom ordering of resources in a pool.

resourceNames

Collection

List of resources to add/remove from the pool.

resourcePoolDisabled

Boolean

True means the resourcePool will not be allocated to job steps.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->createResourcePool(<resourcePoolName>, {<optionals>});
▼

ectool

ectool createResourcePool resourcePoolName [optionals]
▼

deleteResource

Deletes a resource.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->deleteResource(<resourceName>);
▼

ectool

ectool deleteResource resourceName
▼

deleteResourcePool

Deletes a resource pool.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->deleteResourcePool(<resourcePoolName>);
▼

ectool

ectool deleteResourcePool resourcePoolName
▼

getResource

Retrieves a resource by its name.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->getResource(<resourceName>);
▼

ectool

ectool getResource resourceName
▼

getResourcePool

Retrieves a specified resource pool by name.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->getResourcePool(<resourcePoolName>);
▼

ectool

ectool getResourcePool resourcePoolName
▼

getResourcePools

Retrieves a list of resource pools.

Arguments

None.

Positional arguments

None.

Usage

ec-perl

$cmdr->getResourcePools();
▼

ectool

ectool getResourcePools
▼

getResources

Retrieves all resources.

Arguments

None.

Positional arguments

None.

Usage

ec-perl

$cmdr->getResources();
▼

ectool

ectool getResources
▼

getResourcesInEnvironmentTier

Retrieves the list of resources in an environment tier.

Arguments

Argument Name Type Description

projectName

String

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

environmentName

String

(Required) The name of the environment.

environmentTierName

String

(Required) Name for the environment tier; must be unique among all tiers for the environment.

Positional arguments

projectName, environmentName, environmentTierName

Usage

ec-perl

$cmdr->getResourcesInEnvironmentTier(<projectName>, <environmentName>, <environmentTierName>);
▼

ectool

ectool getResourcesInEnvironmentTier projectName environmentName environmentTierName
▼

getResourcesInPool

Retrieves a list of resources in a pool.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) The name of the resource pool.

jobStepId

UUID

If non-null, will be used as context object for orderingFilter expansions.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->getResourcesInPool(<resourcePoolName>, {<optionals>});
▼

ectool

ectool getResourcesInPool resourcePoolName [optionals]
▼

getResourceUsage

Retrieves resource usage information.

Arguments

None.

Positional arguments

None.

Usage

ec-perl

$cmdr->getResourceUsage();
▼

ectool

ectool getResourceUsage
▼

modifyResource

Modifies an existing resource. For a proxy resource, the proxyHostName and proxyPort arguments refer to the proxying CloudBees CD/RO agent. The hostName and port arguments refer to the proxy target.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

artifactCacheDirectory

String

Artifact cache directory for this resource.

block

Boolean

True to block on the agent ping before returning.

description

String

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

hostName

String

The domain name or IP address of the server machine corresponding to this resource.

hostType

String

The type of the host.

newName

String

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

pools

String

DEPRECATED: A list of arbitrary names separated by spaces, indicating the pools with which this resource is associated.

port

Integer

Port number to use when connecting to the agent for this resource; defaults to server default.

proxyCustomization

String

Proxy specific customization data; defaults to none.

proxyHostName

String

The domain name or IP address of the proxy agent machine corresponding to this resource.

proxyPort

Integer

Port number to use when connecting to the proxy agent for this resource; defaults to server default.

proxyProtocol

String

The protocol to use when proxying to this resource; defaults to none.

repositoryNames

String

A newline delimited list of repositories to retrieve artifacts from.

resourceDisabled

Boolean

True means this resource will not be allocated to job steps, regardless of its step limit.

resourcePools

String

A list of arbitrary names separated by comma, indicating the pools with which this resource is associated.

shell

String

Name of the shell program that will execute the command and postprocessor for the step.

stepLimit

Integer

The maximum number of steps that may execute simultaneously using this resource.

trusted

Boolean

True means the agent can speak to all other trusted agents in its zone. An untrusted agent can only speak to gateway agents.

useSSL

Boolean

True means SSL is used for communication.

workspaceName

String

The name of the workspace.

zoneName

String

Name for the zone; must be unique among all zones.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->modifyResource(<resourceName>, {<optionals>});
▼

ectool

ectool modifyResource resourceName [optionals]
▼

modifyResourcePool

Modifies an existing resource pool.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

autoDelete

Boolean

If true, the pool is deleted when the last resource is deleted.

description

String

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

newName

String

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

orderingFilter

String

JavaScript fragment that returns custom ordering of resources in a pool.

resourceNames

Collection

List of resources to add/remove from the pool.

resourcePoolDisabled

Boolean

True means the resourcePool will not be allocated to job steps.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->modifyResourcePool(<resourcePoolName>, {<optionals>});
▼

ectool

ectool modifyResourcePool resourcePoolName [optionals]
▼

pingAllResources

Pings all resources.

Arguments

Argument Name Type Description

block

Boolean

If true, the operation blocks until all resources have been pinged.

enabledOnly

Boolean

If true, the operation checks only enabled resources.

Positional arguments

None.

Usage

ec-perl

$cmdr->pingAllResources({<optionals>});
▼

ectool

ectool pingAllResources [optionals]
▼

pingResource

Pings the specified resource.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->pingResource(<resourceName>);
▼

ectool

ectool pingResource resourceName
▼

removeResourceFromEnvironmentTier

Removes a resource from the specified environment tier.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the resource; must be unique among all resources.

projectName

String

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

environmentName

String

(Required) The name of the environment.

environmentTierName

String

(Required) Name for the environment tier; must be unique among all tiers for the environment.

Positional arguments

resourceName, projectName, environmentName, environmentTierName

Usage

ec-perl

$cmdr->removeResourceFromEnvironmentTier(<resourceName>, <projectName>, <environmentName>, <environmentTierName>);
▼

ectool

ectool removeResourceFromEnvironmentTier resourceName projectName environmentName environmentTierName
▼

removeResourcesFromPool

Removes resources from the specified resource pool.

Arguments

Argument Name Type Description

resourcePoolName

String

(Required) Name for the resource pool; must be unique among all resource pools.

resourceNames

Collection

List of resources to add/remove from the pool.

Positional arguments

resourcePoolName

Usage

ec-perl

$cmdr->removeResourcesFromPool(<resourcePoolName>, {<optionals>});
▼

ectool

ectool removeResourcesFromPool resourcePoolName [optionals]
▼

runDiscovery

Runs the Discover procedure in a plugin to discover contents of a list or set of resources, and store settings for them in the ec_discovery property sheets.

Arguments

Argument Name Type Description

pluginKey

String

(Required) Version independent name of the plugin.

pluginName

String

(Required) The name of the plugin.

projectName

String

(Required) The name of the project.

environmentName

String

(Required) The name of the environment.

environmentTierName

String

(Required) The name of the environment tier.

configurationName

String

(Required) The name of the plugin configuration.

resourceNames

Collection

List of resources to use for discovery.

Positional arguments

pluginKey, pluginName, projectName, environmentName, environmentTierName, configurationName

Usage

ec-perl

$cmdr->runDiscovery(<pluginKey>, <pluginName>, <projectName>, <environmentName>, <environmentTierName>, <configurationName>, {<optionals>});
▼

ectool

ectool runDiscovery pluginKey pluginName projectName environmentName environmentTierName configurationName [optionals]
▼

tearDownResource

Used to tear down a dynamic resource that is no longer needed.

Arguments

Argument Name Type Description

resourceName

String

(Required) Name for the dynamic resource.

Positional arguments

resourceName

Usage

ec-perl

$cmdr->tearDownResource(<resourceName>);
▼

ectool

ectool tearDownResource resourceName
▼

tearDownResourcePool

Used to get rid of resource pools that are no longer needed, and tear down associated dynamic resources.

Arguments

Argument Name Type Description

resourcePoolName

String

Name for the resource pool.

Positional arguments

None.

Usage

ec-perl

$cmdr->tearDownResourcePool({<optionals>});
▼

ectool

ectool tearDownResourcePool [optionals]
▼
Report object type
Rolling deploy