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

JobStep

6 minute readReference

abortJobStep

Abort a running jobStep.

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

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

Returns 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

Filters

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

Returns jobSteps that pass some filter in sequential execution order.

Arguments

Argument Name Type Description

filters

Filter array

Filters

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.

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

Returns 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

Modify the status of an externally managed jobStep.

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

Allow a job step which is waiting on a manual input for performing 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