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

JobStep

6 minute readReference

abortJobStep

Abort a running job step.

Arguments

Argument Name Type Description

jobStepId

String

The primary key for a job step. (Required)

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.

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.abortJobStep(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼

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

String

The primary key for a job step. (Required)

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

String

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

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.completeJobStep(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼

completeManualProcessStep

Completes a manual process step.

Arguments

Argument Name Type Description

jobStepId

String

The primary key for a job step. (Required)

action

String

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

actualParameters

ActualParameter array

Actual parameters passed to the specified job step.

comment

String

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

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.completeManualProcessStep(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼

countJobSteps

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

Arguments

Argument Name Type Description

jobStepId

String

The primary key for a job step. (Required)

filters

Filter array

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

viewName

String

The name of the view.

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.countJobSteps(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼

createJobStep

Create a job step in an existing job.

When invoked in the context of a job step, COMMANDER_JOBSTEPID will be automatically set as the jobStepId argument value unless jobStepId is already specified.

Arguments

Argument Name Type Description

actualParameters

ActualParameter array

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

Credential array

The list of runtime credentials attached to the job step.

errorHandling

String

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

String

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

String

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

String

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

String

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

String

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.

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.createJobStep(
                /* optional arguments */)
▼

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

Filter array

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

String

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

Select array

Custom properties to project into the query results.

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.findJobSteps(
                /* optional arguments */)
▼

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

String

The primary key for a job step. (Required)

structureOnly

Boolean

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

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.getJobStepDetails(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼

getJobStepStatus

Retrieves the status of a job step.

Arguments

Argument Name Type Description

jobStepId

String

The primary key for a job step. (Required)

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.getJobStepStatus(
                jobStepId: 'test-jobStepId')
▼

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

String

The primary key of the job step.

status

String

The starting status for the step.

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.modifyJobStep(
                /* optional arguments */)
▼

retryProcessStep

Allows a job step that is waiting on manual input to perform a retry.

Arguments

Argument Name Type Description

jobStepId

String

The primary key for a job step. (Required)

action

String

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

comment

String

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

Usage

import com.electriccloud.client.groovy.ElectricFlow
import com.electriccloud.client.groovy.models.*


ElectricFlow ef = new ElectricFlow()

def result = ef.retryProcessStep(
                jobStepId: 'test-jobStepId'
                /* optional arguments */)
▼
job
kerberoskeytab