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

Job

12 minute readReference

abortAllJobs

Aborts all running jobs.

Arguments

Argument Name Type Description

force

Boolean

True to force abort the jobs.

reason

String

String added to the job error message.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool abortAllJobs [optionals]
▼

abortJob

Aborts a running job.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

force

Boolean

Instructs certain API calls to continue, even though doing to might have consequences. For example, if true, for abortJob, alwaysRun steps will be aborted as well; for import, existing objects will be replaced. If true, setDatabaseConfiguration will store the configuration even if it can’t be validated.

reason

String

User-supplied string.

Positional arguments

jobId

Usage

ec-perl

$cmdr->abortJob(<jobId>, {<optionals>});
▼

ectool

ectool abortJob jobId [optionals]
▼

abortJobStep

Aborts any type of running step, including a command step or subprocedure step.

Aborting a subprocedure step also aborts all steps of the subprocedure. Steps marked always run still run to completion unless the force argument is set to true.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key for a job step.

force

Boolean

Instructs certain API calls to continue, even though doing to might have consequences. For example, if true, for abortJob, alwaysRun steps will be aborted as well; for import, existing objects will be replaced. If true, setDatabaseConfiguration will store the configuration even if it can’t be validated.

reason

String

User-supplied string.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->abortJobStep(<jobStepId>, {<optionals>});
▼

ectool

ectool abortJobStep jobStepId [optionals]
▼

completeJob

Completes an externally managed job. Marks the job root step so the job is marked completed when all child steps are completed, and updates the runtime for the root step.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

force

Boolean

Instructs certain API calls to continue, even though doing to might have consequences. For example, if true, for abortJob, alwaysRun steps will be aborted as well; for import, existing objects will be replaced. If true, setDatabaseConfiguration will store the configuration even if it can’t be validated.

outcome

JobOutcome

Overall outcome for a job or step: success, warning, error, or skipped.

Positional arguments

jobId

Usage

ec-perl

$cmdr->completeJob(<jobId>, {<optionals>});
▼

ectool

ectool completeJob jobId [optionals]
▼

completeJobStep

Completes an externally managed job step. Marks the job step completed when all child steps are completed and updates the step runtime.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key for a job step.

exitCode

Integer

The exit code of the job step.

force

Boolean

Instructs certain API calls to continue, even though doing to might have consequences. For example, if true, for abortJob, alwaysRun steps will be aborted as well; for import, existing objects will be replaced. If true, setDatabaseConfiguration will store the configuration even if it can’t be validated.

outcome

JobOutcome

Overall outcome for a job or step: success, warning, error, or skipped.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->completeJobStep(<jobStepId>, {<optionals>});
▼

ectool

ectool completeJobStep jobStepId [optionals]
▼

countJobSteps

Retrieves number of job steps in hierarchy under the parent one.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key for a job step.

filters

Collection

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

viewName

String

The name of the view.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->countJobSteps(<jobStepId>, {<optionals>});
▼

ectool

ectool countJobSteps jobStepId [optionals]
▼

createJob

Creates an externally managed job that serves as a container for external job steps.

Arguments

Argument Name Type Description

destinationProject

String

The project that will own the job.

jobNameTemplate

String

Template used to determine the default name of jobs launched from a procedure.

procedureName

String

The name of the procedure that should own the job step. If not specified, myStep.procedure is used.

projectName

String

The name of the project if destinationProject is not specified.

status

JobStatus

The starting status for the job.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool createJob [optionals]
▼

createJobStep

Use this API to add CloudBees CD/RO managed job steps to a running job or job step and to create externally managed steps if the external argument is set to true.

You must specify the parent job step using either the jobStepId or parentPath arguments (COMMANDER_JOBSTEPID ` implicitly sets `jobStepId ). The parent job step status must not be completed.

External job steps do not participate in error handling processing. When you execute a job that includes a step with the --errorhandling abortProcedureNow argument, this argument is ignored if the step fails. The job then continues running the rest of the steps.

Arguments

Argument Name Type Description

actualParameters

Map

Actual parameters passed to an invoked subprocedure.

alwaysRun

Boolean

True means this step will run even if preceding steps fail in a way that aborts the job.

broadcast

Boolean

True means replicate this step to execute (in parallel) on each of the specified resources (that is, for a pool, run the step on each of the resources in the pool).

command

String

Script to execute the functions of this step; passed to the step’s shell for execution.

comment

String

Script to execute the functions of this step; passed to the step’s shell for execution.

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.

credentialName

String

The name of the credential to be used for impersonation.

credentials

Collection

The list of runtime credentials attached to the job step.

errorHandling

ErrorHandling

Specifies error handling for this step.

exclusive

Boolean

True means the resource acquired for this step will be retained for the exclusive use of this job. This means 2 things: first, no other job will be able to use that resource, regardless of its step limit, until this job completes; second, future steps for this job will use the resource in preference to other resources, if this resource meets the needs of the steps and its step limit is not exceeded.

exclusiveMode

ExclusiveMode

Determines the mode to use when the step acquires a resource. If set to none, then the default behavior for the step applies. If set to job, then the resource will be retained for the exclusive use of this job. If set to step, then the resource will be retained for the exclusive use of this step and procedure it may call. If set to call, then the resource will be retained for the exclusive use of all steps within the current procedure call.

external

Boolean

True if the step is externally managed (no state machine).

jobStepId

UUID

The primary key of the job step.

jobStepName

String

The name for the new step. If omitted, a default name will be generated.

logFileName

String

Name of the log file for a step; specified relative to the root directory in the job’s workspace.

parallel

Boolean

True means this step and all adjacent steps with the flag set will run in parallel.

parentPath

String

Path to the parent job step. If a parent step is not specified, the current job step is used.

postProcessor

String

This command runs in parallel with the main command for the step; it analyzes the log for the step and collects diagnostic information.

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.

procedureName

String

The name of the procedure that should own the job step. If not specified, myStep.procedure is used.

projectName

String

The name of the project for procedureName.

releaseExclusive

Boolean

True means the resource acquired for this step will be no longer be retained for the exclusive use of this job when this step completes.

releaseMode

ReleaseMode

Determines the mode to use when the step releases its resource. If set to none, the default behavior applies. If set to release, then the resource will be available for use by any job. If set to releaseToJob, then the resource will be available for use by any step in this job.

resourceName

String

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

shell

String

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

status

JobStatus

The starting status for the step.

stepName

String

The name of the procedure step that should own the job step. If not specified, myStep is used.

subprocedure

String

Name of a procedure to invoke during this step.

subproject

String

Name of the project containing the procedure to invoke during this step.

timeLimit

String

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

timeLimitUnits

TimeLimitUnits

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

workingDirectory

String

Working directory in which to execute the command for this step. A relative name is interpreted relative to the root directory for the job’s workspace.

workspaceName

String

The name of the workspace.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool createJobStep [optionals]
▼

deleteJob

Deletes a job from the CloudBees CD/RO database.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

waitForDeleteToComplete

Boolean

If true, wait for the job to finish deleting before returning from the call.

Positional arguments

jobId

Usage

ec-perl

$cmdr->deleteJob(<jobId>, {<optionals>});
▼

ectool

ectool deleteJob jobId [optionals]
▼

findJobSteps

Retrieves a list of job steps from a single job or from a single subprocedure job step. This command is used by the Job Details web page in the CloudBees CD/RO UI. The elements in the list are returned in their natural job order.

Arguments

Argument Name Type Description

filters

Collection

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

firstResult

Integer

The first result to be retrieved, numbered from 0.

jobId

String

The primary key of the job, or the name of the job.

jobStepId

UUID

The primary key for a job step.

maxIds

Integer

The maximum number of object IDs to return.

numObjects

Integer

The number of objects to return as the first page of results.

selects

Collection

Custom properties to project into the query results.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool findJobSteps [optionals]
▼

getJobDetails

Retrieves complete information about a job, including details from each job step.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

structureOnly

Boolean

Reduces the amount of information returned by some api calls to minimal structural information.

Positional arguments

jobId

Usage

ec-perl

$cmdr->getJobDetails(<jobId>, {<optionals>});
▼

ectool

ectool getJobDetails jobId [optionals]
▼

getJobInfo

Retrieves all information about a job, except for job step information.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

Positional arguments

jobId

Usage

ec-perl

$cmdr->getJobInfo(<jobId>);
▼

ectool

ectool getJobInfo jobId
▼

getJobNotes

Retrieves the notes property sheet from a job.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

Positional arguments

jobId

Usage

ec-perl

$cmdr->getJobNotes(<jobId>);
▼

ectool

ectool getJobNotes jobId
▼

getJobs

Retrieves summary information for a list of jobs. By default, all jobs are returned.

If you use sortKey or sortOrder, you must use both arguments together. You can use firstResult and maxResults together or separately to select a limited sublist of jobs for the result set.

Arguments

Argument Name Type Description

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.

status

String

Filter jobs by this status.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool getJobs [optionals]
▼

getJobsForSchedule

Retrieves jobs started by a specific schedule.

Arguments

Argument Name Type Description

projectName

String

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

scheduleName

String

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

Positional arguments

projectName, scheduleName

Usage

ec-perl

$cmdr->getJobsForSchedule(<projectName>, <scheduleName>);
▼

ectool

ectool getJobsForSchedule projectName scheduleName
▼

getJobStatus

Retrieves the status of a job.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

Positional arguments

jobId

Usage

ec-perl

$cmdr->getJobStatus(<jobId>);
▼

ectool

ectool getJobStatus jobId
▼

getJobStepDetails

Retrieves details for a job step. You may never need to use this command. This information is available for all job steps in a job by using the getJobDetails command. The getJobStepDetails command can be used to refresh data for a single step if you need an update in real time.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key for a job step.

structureOnly

Boolean

Reduces the amount of information returned by some api calls to minimal structural information.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->getJobStepDetails(<jobStepId>, {<optionals>});
▼

ectool

ectool getJobStepDetails jobStepId [optionals]
▼

getJobStepStatus

Retrieves the status of a job step.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key for a job step.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->getJobStepStatus(<jobStepId>);
▼

ectool

ectool getJobStepStatus jobStepId
▼

getJobSummaries

Retrieves summary information about jobs.

Arguments

Argument Name Type Description

filters

Collection

How to filter the results.

includeLastSuccess

Boolean

Whether to include the last successful job, if not otherwise included.

maxFailedSteps

Integer

The maximum number of failed steps to return.

maxJobs

Integer

The maximum number of jobs to return.

maxRunningSteps

Integer

The maximum number of running steps to return.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool getJobSummaries [optionals]
▼

getJobSummary

Retrieves a job and its job steps with only the specified job and job step properties.

Arguments

Argument Name Type Description

jobId

String

The primary key of the job, or the name of the job.

jobProperties

String

A comma-separated list of intrinsic job properties to include in the output.

jobStepProperties

String

A comma-separated list of intrinsic job step properties to include in the output.

orderStepsByIndex

Boolean

Each job step has a step index which defines its relative position within its parent step.Set this to true to return the results in the ascending order of the step index.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool getJobSummary [optionals]
▼

modifyJob

Modifies the status of an externally managed job.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

status

JobStatus

The starting status for the job.

Positional arguments

jobId

Usage

ec-perl

$cmdr->modifyJob(<jobId>, {<optionals>});
▼

ectool

ectool modifyJob jobId [optionals]
▼

modifyJobStep

Transitions an externally managed job step through its lifecycle (pending, runnable, running, or complete) by setting the step’s status property.

Arguments

Argument Name Type Description

jobStepId

UUID

(Required) The primary key of the job step.

status

JobStatus

The starting status for the step.

Positional arguments

jobStepId

Usage

ec-perl

$cmdr->modifyJobStep(<jobStepId>, {<optionals>});
▼

ectool

ectool modifyJobStep jobStepId [optionals]
▼

moveJobs

Moves jobs from one project to another project.

Arguments

Argument Name Type Description

sourceProject

String

(Required) Source project for jobs.

destinationProject

String

(Required) Project that will own the jobs.

Positional arguments

sourceProject, destinationProject

Usage

ec-perl

$cmdr->moveJobs(<sourceProject>, <destinationProject>);
▼

ectool

ectool moveJobs sourceProject destinationProject
▼

provisionCluster

Provisions a cluster.

Arguments

Argument Name Type Description

projectName

String

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

clusters

Collection

A list of clusters that belongs to the environment which need to be provisioned.

environmentName

String

Name of the environment which owns this cluster.

Positional arguments

projectName

Usage

ec-perl

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

ectool

ectool provisionCluster projectName [optionals]
▼

runProcedure

Creates and starts a new job using a procedure directly or a procedure specified indirectly through a schedule.

Returns a new job ID when the job completes. If the pollInterval option is provided, wait until the job completes up to a maximum of timeout seconds (if also provided). If the scheduleName option is provided, the parameters provided by that schedule are used.

runProcedure credentials - two types of credentials can be passed to runProcedure :

  • Impersonation credentials

  • Credential parameters

Impersonation credentials

Impersonation credentials are used to set the top level impersonation credential for a job. If specified, the impersonation credential [on the job] is used as the default impersonation credential for all steps in the job.

The impersonation credential can be specified in two ways. If the credentialName argument is supplied, the job looks for the named credential specified. If the user has execute permission on the specified credential, runProcedure is allowed to start the job.

If the userName and password arguments are supplied, the job creates a transient credential to contain the pair. The transient credential is used by the job and then discarded when the job completes.

Only one of credentialName or userName should be specified. If both are specified, only userName is used. Neither can be specified if the procedure being run already has a credential defined on the procedure or the project.

Credential parameters

If the procedure defines one or more credential parameters, runProcedure must specify a credential to use for each parameter. The actualParameter argument identifies the credential name to use for the parameter, and the credential argument specifies the user name for each defined credential. For each credential specified, runProcedure prompts for a password.

Credential reference parameters

If the procedure defines one or more credential reference parameters, that is, a parameter that references a credential from an external credential provider, runProcedure must specify a credential reference to use for each parameter. The credentialReferenceParameter argument identifies the reference to the credential name to use for the parameter.

Multiple credential references can be specified by having additional name=value pairs after the credentialReferenceParameter arguments. The same credential reference can be specified as the value for more than one actual parameter.

The pollInterval and timeout arguments are used to control whether runProcedure returns immediately or waits until the job completes. If pollInterval is used and timeout is not used, pollInterval will time out in 60 seconds.

Arguments

Argument Name Type Description

projectName

String

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

actualParameters

Map

Parameters passed as arguments to the procedure.

credentialName

String

The name of the credential argument.

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

destinationProject

String

The project that will own the job.

parsedWebhookData

String

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

password

String

Secret value used to identify the account for a particular user.

priority

JobPriority

The priority of the job.

procedureName

String

Name for the procedure; must be unique within the project.

scheduleName

String

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

userName

String

User name under which you wish to login.

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

Usage

ec-perl

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

ectool

ectool runProcedure projectName [optionals]
▼

setJobName

Sets the name of a running job.

  • The jobId can be omitted if the command is run as part of a CloudBees CD/RO step.

  • A job cannot be renamed after it has completed.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

newName

String

(Required) The new name for the job.

Positional arguments

jobId, newName

Usage

ec-perl

$cmdr->setJobName(<jobId>, <newName>);
▼

ectool

ectool setJobName jobId newName
▼

waitForJob

Waits until the specified job reaches a given status or the timeout expires.

This command is only supported with ec-perl.

Arguments

Argument Name Type Description

jobId

UUID

(Required) The job to wait for.

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

timeout

Integer

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

The default is 60 seconds.

finalStatus

String

The status to wait for. Must be either running or completed (the default is completed).

Positional arguments

jobId

Usage

ec-perl

$cmdr->waitForJob(<jobId>, {<optionals>});
▼
Installing or upgrading remote agents
Kerberos keytab