Job Management

abortAllJobs

Aborts all running jobs.

Arguments Descriptions

Arguments	Descriptions
force	(Optional) < Boolean flag— `0\|1\|true\|false` > If this is set to `1` or `true`, the job aborts immediately. A zero value allows jobs to terminate in an orderly way, executing steps marked “always run". Argument type: Boolean
reason	(Optional) A string added to the aborted `job/jobstep` that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description. Argument type: String

force

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

If this is set to 1 or true, the job aborts immediately. A zero value allows jobs to terminate in an orderly way, executing steps marked “always run".

Argument type: Boolean

reason

(Optional) A string added to the aborted job/jobstep that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description.

Argument type: String

Positional arguments

None

Response

None or a status OK message.

ec-perl

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

Example

$cmdr\->abortAllJobs({force => 1});▼

ectool

syntax: ectool abortAllJobs [optionals]

Example

ectool abortAllJobs --force 1▼

Back to top

abortJob

Aborts a running job.

You must enter a jobId.

Arguments Descriptions

Arguments	Descriptions
jobId	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. Argument type: UUID
force	(Optional) < Boolean flag— `0\|1\|true\|false` > If this is set to `1` or true , the job aborts immediately. A zero value allows jobs to terminate in an orderly way, executing steps marked "always run". Argument type: Boolean
reason	(Optional) A string added to the aborted `job/jobstep` that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description. Argument type: String

jobId

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.

Argument type: UUID

force

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

If this is set to 1 or true , the job aborts immediately. A zero value allows jobs to terminate in an orderly way, executing steps marked "always run".

Argument type: Boolean

reason

(Optional) A string added to the aborted job/jobstep that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description.

Argument type: String

Positional arguments

jobId

Response

None or a status OK message.

ec-perl

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

Example

$cmdr\->abortJob(4fa765dd-73f1-11e3-b67e-b0a420524153, {force => 1});▼

ectool

syntax: ectool abortJob <jobId> [optionals]

Example

ectool abortJob 4fa765dd-73f1-11e3-b67e-b0a420524153 --force 1▼

Back to top

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" will still run to completion unless the "force" flag is specified.

You must enter a jobStepId.

Arguments Descriptions

Arguments	Descriptions
jobStepId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job step that is assigned automatically when the job step is created. The system also accepts a job step name assigned to the job step by its name template. Argument type: UUID
force	(Optional) < Boolean flag— `0\|1\|true\|false` > If this is set to 1 or true , the job aborts immediately. A zero value allows jobs to terminate in an orderly way, for example, executing steps marked "always run". Argument type: Boolean
reason	(Optional) A string added to the aborted `job/jobstep` that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description. Argument type: String

jobStepId

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

Argument type: UUID

force

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

If this is set to 1 or true , the job aborts immediately. A zero value allows jobs to terminate in an orderly way, for example, executing steps marked "always run".

Argument type: Boolean

reason

(Optional) A string added to the aborted job/jobstep that describes or records the reason for the abort. The server records this value, but places no meaning on the string, which is similar to a text description.

Argument type: String

Positional arguments

jobStepId

Response

None or a status OK message.

ec-perl

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

Example

$cmdr->abortJobStep(5da765dd-73f1-11e3-b67e-b0a420524153, {force => 1});▼

ectool

syntax: ectool abortJobStep <jobStepId> [optionals]

Example

ectool abortJobStep 5da765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

deleteJob

Deletes a job from the CloudBees CD/RO database.

You must specify a jobId.

Arguments Descriptions

Arguments	Descriptions
jobId	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. Argument type: UUID
waitForDeleteToComplete	(Optional) < Boolean flag— `0\|1\|true\|false` > If this is set to 1 or true , CloudBees CD/RO deletes the jobs after completing it. If the value is 0 ` or `false, the job is deleted immediately. Argument type: Boolean

jobId

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.

Argument type: UUID

waitForDeleteToComplete

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

If this is set to 1 or true , CloudBees CD/RO deletes the jobs after completing it. If the value is 0 ` or `false, the job is deleted immediately.

Argument type: Boolean

Positional arguments

jobId

Response

None or a status OK message.

ec-perl

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

Example

$cmdr->deleteJob(4fa765dd-73f1-11e3-b67e-b0a420524153, {waitForDeleteToComplete => 0});▼

ectool

syntax: ectool deleteJob <jobId> [<optionals>]

Example

ectool deleteJob 4fa765dd-73f1-11e3-b67e-b0a420524153 --waitForDeleteToComplete 0▼

Back to top

findJobSteps

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

You must specify either a jobId or a jobStepId, but not both.

Arguments Descriptions

Arguments	Descriptions
jobId	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. Argument type: UUID
jobStepId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job step that is assigned automatically when the job step is created. The system also accepts a job step name assigned to the job step by its name template. Argument type: UUID
filters	A list of zero or more filter criteria definitions used to define objects to find. See the `findObjects` API for complete description for using filters. Argument type: Collection
numObjects	`<full object count>` This specifies the number of full job steps (not just the IDs) returned in the response. Returned job steps will be from the beginning of the list. If `numObjects` is not specified, all job steps in the list of object IDs are returned. Any and all job steps can be retrieved using the `getObjects` command. Argument type: Integer
selects	This is an unordered list of property names that specify additional top-level properties to return for each object. See the code example for `findObjects` for instructions on forming the list and passing it to the CloudBees CD/RO Perl API. Argument type: Collection

jobId

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.

Argument type: UUID

jobStepId

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

Argument type: UUID

filters

A list of zero or more filter criteria definitions used to define objects to find. See the findObjects API for complete description for using filters.

Argument type: Collection

numObjects

<full object count> This specifies the number of full job steps (not just the IDs) returned in the response. Returned job steps will be from the beginning of the list. If numObjects is not specified, all job steps in the list of object IDs are returned. Any and all job steps can be retrieved using the getObjects command.

Argument type: Integer

selects

This is an unordered list of property names that specify additional top-level properties to return for each object. See the code example for findObjects for instructions on forming the list and passing it to the CloudBees CD/RO Perl API.

Argument type: Collection

Positional arguments

jobId or jobStepId

Response

One or more jobStep elements.

ec-perl

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

Example 1

my $xPath = $cmdr\->findJobSteps(
               {jobId   => "4fa765dd-73f1-11e3-b67e-b0a420524153",
                select  => [{propertyName  => 'charEncoding'},
                            {propertyName  => 'abc'}]});
     print "Return data from {PRODUCT} :\n" .
               $xPath-> findnodes_as_string("/"). "\n";▼

Example 2

my $xPath = $cmdr\->findJobSteps({jobStepId  => "5da765dd-73f1-11e3-b67e-b0a420524153"});
   print "Return data from {PRODUCT} :\n" .
        $xPath-> findnodes_as_string("/"). "\n";▼

ectool

Not supported.

Back to top

getJobDetails

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

You must specify a jobId.

Arguments Descriptions

Arguments	Descriptions
jobId	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. Argument type: UUID
structureOnly	(Optional) < Boolean flag— `0\|1\|true\|false` > If this is set to `1` or `true`, the amount of information returned is reduced to minimal structural information. Argument type: Boolean

jobId

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.

Argument type: UUID

structureOnly

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

If this is set to 1 or true, the amount of information returned is reduced to minimal structural information.

Argument type: Boolean

Positional arguments

jobId

Response

One job element, including one or more jobStep elements.

ec-perl

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

Example

$cmdr->getJobDetails(4fa765dd-73f1-11e3-b67e-b0a420524153, {structureOnly => 1});▼

ectool

syntax: ectool getJobDetails <jobId> [optionals]

Example

ectool getJobDetails 4fa765dd-73f1-11e3-b67e-b0a420524153 --structureOnly 1▼

Back to top

getJobInfo

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

You must specify a jobId.

Arguments	Descriptions
jobId	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. Argument type: UUID

Arguments

Descriptions

jobId

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.

Argument type: UUID

Positional arguments

jobId

Response

One job element.

ec-perl

syntax: $cmdr->getJobInfo(<jobId>);

Example

$cmdr->getJobInfo(4fa765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool getJobInfo <jobId>

Example

ectool getJobInfo 4fa765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

getJobNotes

Retrieves the notes property sheet from a job.

You must specify a jobId.

Arguments	Descriptions
jobId	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. Argument type: UUID

Arguments

Descriptions

jobId

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.

Argument type: UUID

Positional arguments

jobId

Response

A propertySheet element that contains the job.

ec-perl

syntax: $cmdr->getJobNotes(<jobId>);

Example

$cmdr->getJobNotes(4fa765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool getJobNotes <jobId>

Example

ectool getJobNotes 4fa765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

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 Descriptions

Arguments	Descriptions
firstResult	The first row to return in the results. This is the < index number > 0-based index that identifies the first element returned from filtered, sorted result set. Argument type: Integer
maxResults	This number, < result count >, sets the maximum number of returned jobs. Argument type: Integer
sortKey	How to sort the results: `<jobId\|jobName\|start\|finish\|procedureName>`. Argument type: String
sortOrder	The order in which to sort the results: `<ascending\|descending>`. Argument type: SortOrder
status	Filter jobs by this status: `<running\|completed\|runnable>`. Argument type: String

firstResult

The first row to return in the results.

This is the < index number > 0-based index that identifies the first element returned from filtered, sorted result set.

Argument type: Integer

maxResults

This number, < result count >, sets the maximum number of returned jobs.

Argument type: Integer

sortKey

How to sort the results: <jobId|jobName|start|finish|procedureName>.

Argument type: String

sortOrder

The order in which to sort the results: <ascending|descending>.

Argument type: SortOrder

status

Filter jobs by this status: <running|completed|runnable>.

Argument type: String

Positional arguments

None

Response

One or more job elements. A job element contains summary information only.

ec-perl

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

Examples

How do I get the first 10 jobs (index 0-9)?

$cmdr\-> getJobs ({maxResults=>10});▼

How do I get the next 10 jobs (index 10-19)?

$cmdr\-> getJobs({firstResult=>10, maxResults=>10});▼

How do I get the most recent job by start time?

$cmdr\-> getJobs({sortKey=>'start', sortOrder=>'descending', maxResults=>1});▼

ectool

syntax: ectool getJobs [optionals]

Examples

How do I get the first 10 jobs (index 0-9)?

ectool getJobs --maxResults 10▼

How do I get the next 10 jobs (index 10-19)?

ectool getJobs --firstResult 10 --maxResults 10▼

How do I get the most recent job by start time?

ectool getJobs --sortKey start --sortOrder descending --maxResults 1▼

Back to top

getJobsForSchedule

Retrieves jobs started by a specific schedule.

You must specify a projectName and scheduleName.

Arguments	Descriptions
projectName	The name for the project that must be unique among all projects. Argument type: String
scheduleName	The name for the schedule that must be unique among all schedules for the project. Argument type: String

Arguments

Descriptions

projectName

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

Argument type: String

scheduleName

The name for the schedule that must be unique among all schedules for the project.

Argument type: String

Positional arguments

projectName, scheduleName

Response

Returns an XML stream containing any number of job elements. The job elements contain summary information only.

ec-perl

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

Example

$cmdr->getJobsForSchedule('QA Tests', 'Required');▼

ectool

syntax: ectool getJobsForSchedule <projectName> <scheduleName>

Example

ectool getJobsForSchedule 'QA Tests' 'Required'▼

Back to top

getJobStatus

Retrieves the status of a job.

You must specify the jobId.

Arguments	Descriptions
jobId	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. Argument type: UUID

Arguments

Descriptions

jobId

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.

Argument type: UUID

Positional arguments

jobId

Response

Values for status and outcome as follows:

Possible values for status :

pending —The job is not yet runnable—it is waiting for other steps to complete first. A job should not stay in this state for longer than a few seconds.

runnable —The job is ready to run, but it is waiting for a resource to become available.

running —The job is assigned to a resource and is executing the step command.

completed —The job finished executing.

Possible values for outcome : The outcome is accurate only if the job status is "completed."

success —The job finished successfully.

warning —The job completed with no errors, but encountered some suspicious conditions.

error —The job has finished execution with errors.

ec-perl

syntax: $cmdr->getJobStatus(<jobId>);

Example

$cmdr->getJobStatus(4fa765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool getJobStatus <jobId>

Example

ectool getJobStatus 4fa765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

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.

You must specify jobStepId.

Arguments Descriptions

Arguments	Descriptions
jobStepId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job step that is assigned automatically when the job step is created. The system also accepts a job step name assigned to the job step by its name template. Argument type: UUID
structureOnly	(Optional) < Boolean flag — < `0\|1\|true\|false` > c `true`, the amount of information returned is reduced to minimal structural information. Argument type: Boolean

jobStepId

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

Argument type: UUID

structureOnly

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

c true, the amount of information returned is reduced to minimal structural information.

Argument type: Boolean

Positional arguments

jobStepId

Response

A jobStep element.

ec-perl

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

Example

$cmdr->getJobStepDetails(5da765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool getJobStepDetails <jobStepId> [optionals]

Example

ectool getJobStepDetails 5da765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

getJobStepStatus

Retrieves the status of a job step.

You must specify the jobStepId.

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

Arguments

Descriptions

jobStepId

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

Argument type: UUID

Positional arguments

jobStepId

Response

A status tag—for example: <status>completed</status>

Possible values for status :

pending —The job step is not yet runnable—it is waiting for other steps to complete first. A job should not stay in this state for longer than a few seconds.

runnable —The job step is ready to run, but it is waiting for a resource to become available.

running —The job step is assigned to a resource and is executing the step command.

completed —The job step finished executing.

ec-perl

syntax: $cmdr->getJobStepStatus(<jobStepId>);

Example

$cmdr->getJobStepStatus(5da765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool getJobStepStatus <jobStepId>

Example

ectool getJobStepStatus 5da765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

getJobSummaries

Retrieves summary information about jobs.

Arguments Descriptions

Arguments	Descriptions
filters	(Optional) Specify filters in a space-separated list: `filter1 filter2 …` A list of zero or more filter criteria definitions used to define objects to find. Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD/RO Perl API. Two types of filters: "property filters"—used to select objects based on the value of the object’s intrinsic or custom property "boolean filters" ("and", "or", "not")—used to combine one or more filters using boolean logic. Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD/RO or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property. Property filter operators are between (2 operands) contains (1) equals (1) greaterOrEqual (1) greaterThan (1) in (1) lessOrEqual(1) lessThan (1) like (1) notEqual (1) notLike (1) isNotNull (0) isNull (0) A Boolean filter is a Boolean an operator and an array of one or more filters that are operands. Each operand can be either a property filter or a Boolean filter. Boolean operators are: not (1 operand) and (2 or more operands) or (2 or more operands) Argument type: Collection
includeLastSuccess	(Optional) < Boolean flag - `0\|1\|true\|false` > If this is set to `1` or `true`, the step will include the last successful job if it was not already included. Argument type: Boolean
maxFailedSteps	(Optional) Maximum number of failed steps to return. Argument type: Integer
maxJobs	(Optional) Maximum number of jobs to return. Argument type: Integer
maxRunningSteps	(Optional) Maximum number of running steps to return. Argument type: Integer

filters

(Optional) Specify filters in a space-separated list: filter1 filter2 … A list of zero or more filter criteria definitions used to define objects to find.

Each element of the filter list is a hash reference containing one filter criterion. You may specify several filter criteria, in which case an object must meet all filter criteria to be included in the result. See the code example below for instructions on forming the list and passing it to the CloudBees CD/RO Perl API.

Two types of filters:

"property filters"—used to select objects based on the value of the object’s intrinsic or custom property
"boolean filters" ("and", "or", "not")—used to combine one or more filters using boolean logic.

Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by CloudBees CD/RO or a custom property added by the user. Each operator takes zero, one, or two operands to compare against the desired property.

Property filter operators are between (2 operands) contains (1) equals (1) greaterOrEqual (1) greaterThan (1) in (1) lessOrEqual(1) lessThan (1) like (1) notEqual (1) notLike (1) isNotNull (0) isNull (0)

A Boolean filter is a Boolean an operator and an array of one or more filters that are operands. Each operand can be either a property filter or a Boolean filter. Boolean operators are: not (1 operand) and (2 or more operands) or (2 or more operands)

Argument type: Collection

includeLastSuccess

(Optional) < Boolean flag - 0|1|true|false > If this is set to 1 or true, the step will include the last successful job if it was not already included.

Argument type: Boolean

maxFailedSteps

(Optional) Maximum number of failed steps to return.

Argument type: Integer

maxJobs

(Optional) Maximum number of jobs to return.

Argument type: Integer

maxRunningSteps

(Optional) Maximum number of running steps to return.

Argument type: Integer

Positional arguments

None

Response

A summary of the job steps with the specified properties.

ec-perl

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

Example

$cmdr->getJobSummaries ({maxFailedSteps => 6});▼

ectool

syntax: ectool getJobSummaries [optionals]

Example

ectool getJobSummaries --maxFailedSteps 6▼

Back to top

getJobSummary

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

Arguments Descriptions

Arguments	Descriptions
jobId	(Optional) 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. Argument type: UUID
jobProperties	(Optional) A comma-separated list of intrinsic job properties to include in the output. Argument type: String
jobStepProperties	(Optional) A comma-separated list of intrinsic job step properties to include in the output. Argument type: String
orderStepsByIndex	(Optional) < Boolean flag - `0\|1\|true\|false` >. Each job step has a step index that defines its relative position within its parent step. Set this to `1` or `true` to return the results in the ascending order of the step index. Argument type: Boolean

jobId

(Optional)

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.

Argument type: UUID

jobProperties

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

Argument type: String

jobStepProperties

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

Argument type: String

orderStepsByIndex

(Optional) < Boolean flag - 0|1|true|false >. Each job step has a step index that defines its relative position within its parent step. Set this to 1 or true to return the results in the ascending order of the step index.

Argument type: Boolean

Positional arguments

None.

Response

A summary of the jobStep with the specified properties.

ec-perl

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

Example

$cmdr->getJobSummary ({jobId => 5da765dd-73f1-11e3-b67e-b0a420524153});▼

ectool

syntax: ectool getJobSummary [optionals]

Example

ectool getJobSummary --jobId 5da765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

moveJobs

Moves jobs from one project to another project.

You must specify sourceProject and destinationProject.

Arguments	Descriptions
sourceProject	Name of the project that contains the jobs you want to move. Argument type: String
destinationProject	New project that will contain the jobs. Argument type: String

Arguments

Descriptions

sourceProject

Name of the project that contains the jobs you want to move.

Argument type: String

destinationProject

New project that will contain the jobs.

Argument type: String

Positional arguments

sourceProject, destinationProject

Response

None or a status OK message.

ec-perl

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

Example

$cmdr->moveJobs("Default", "Utilities");▼

ectool

syntax: ectool moveJobs <sourceProject> <destinationProject>

Example

ectool moveJobs "Default" "Utilities"▼

Back to top

runProcedure

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

Returns a new job ID. Wait until 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 will be 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, ectool prompts for a password.

For example, for a procedure named proc1 with a single credential parameter named 'param1'. The following command could be used to pass a transient credential where the user name is 'joe' and the password is 'plumber' :

$ectool runProcedure test --procedureName proc1 \
    --actualParameter param1=cred1 --credential cred1=joe▼

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.

For example, consider a procedure named proc1 with a single credential reference parameter named refparam1:

$ectool runProcedure test --procedureName proc1 \
    --actualParameter param1=cred1 --credentialReferenceParameter cred1=refparam1▼

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.

You must specify a projectName and either a procedureName or a scheduleName.

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 Descriptions

Arguments	Descriptions
projectName	Name of the project. This name must be unique among all projects. Argument Type: String Argument type: String
actualParameter	(Optional) Specifies the values to pass as parameters to the called procedure. Each parameter value is specified with an `actualParameterName` and a `value`. The `actualParameterName` must match the name of a formal parameter on the called procedure. Used in conjunction with `procedureName` to set the value of the actual parameters. Do not use this argument with `scheduleName`. Argument type: Map
credentialName	(Optional) `credentialName` can be one of two forms: relative (for example, "cred1" ) —the credential is assumed to be in the project that contains the request target object. absolute (for example, "/projects/BuildProject/credentials/cred1" ) —the credential can be from any specified project, regardless of the target object’s project.
credentials	(Optional) Use the following syntax to specify a local credential: `[<credName>=<userName> [<credName>=<userName> …]]`. For external credentials, use `--credentialReferenceParameter`. Argument type: Collection
credentialReferenceParameter	(Optional) Used when the procedure defines one or more credential reference parameters, that is, a parameter that references a credential from an external credential provider. `[<credName>=<externalCredential> [<credName>=<externalCredential> …]]` For local parameters, use `--credentials`. Argument type: Map
destinationProject	(Optional) This argument is used to specify the name of the destination project. Argument type: String
password	(Optional) The password for the user running the procedure. Argument type: String
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) Priorities take effect when two or more job steps in different jobs are waiting for the same resource. When the resource is available, it will be used by the job step that belongs to the job with the highest priority. If the priority level is the same, the resource will be used by the job step that belongs to the job with the lowest job ID number. If the job steps are in the same job, the resource will be used first by the step with the lowest job step ID number. Priority values are: `low\|normal\|high\|highest`. Argument type: JobPriority
procedureName	(Optional) The name for the procedure; must be unique within the project. Argument type: String
scheduleName	(Optional) The name for the schedule; must be unique among all schedules for the project. Use this option if you want to use the parameters from an existing specific schedule. Argument type: String
timeout	(Optional) This argument requires a value set in seconds . If `pollInterval` 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
userName	(Optional) The name of the user who is running the procedure. Argument type: String
webhookData	(Internal use, only) Free-form string containing information from a webhook callback. This argument is populated internally by webhook aware plugins, such as ECSCM. Argument Type: String

projectName

Name of the project. This name must be unique among all projects.

Argument Type: String

Argument type: String

actualParameter

(Optional) Specifies the values to pass as parameters to the called procedure. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the called procedure. Used in conjunction with procedureName to set the value of the actual parameters. Do not use this argument with scheduleName.

Argument type: Map

credentialName

(Optional) credentialName can be one of two forms: relative (for example, "cred1" ) —the credential is assumed to be in the project that contains the request target object. absolute (for example, "/projects/BuildProject/credentials/cred1" ) —the credential can be from any specified project, regardless of the target object’s project.

credentials

(Optional) Use the following syntax to specify a local credential: [<credName>=<userName> [<credName>=<userName> …]]. For external credentials, use --credentialReferenceParameter.

Argument type: Collection

credentialReferenceParameter

(Optional) Used when the procedure defines one or more credential reference parameters, that is, a parameter that references a credential from an external credential provider.

[<credName>=<externalCredential> [<credName>=<externalCredential> …]]

For local parameters, use --credentials.

Argument type: Map

destinationProject

(Optional) This argument is used to specify the name of the destination project.

Argument type: String

password

(Optional) The password for the user running the procedure.

Argument type: String

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) Priorities take effect when two or more job steps in different jobs are waiting for the same resource. When the resource is available, it will be used by the job step that belongs to the job with the highest priority. If the priority level is the same, the resource will be used by the job step that belongs to the job with the lowest job ID number.

If the job steps are in the same job, the resource will be used first by the step with the lowest job step ID number. Priority values are: low|normal|high|highest.

Argument type: JobPriority

procedureName

(Optional) The name for the procedure; must be unique within the project.

Argument type: String

scheduleName

(Optional) The name for the schedule; must be unique among all schedules for the project. Use this option if you want to use the parameters from an existing specific schedule.

Argument type: String

timeout

(Optional) This argument requires a value set in seconds . If pollInterval 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

userName

(Optional) The name of the user who is running the procedure.

Argument type: String

webhookData

(Internal use, only) Free-form string containing information from a webhook callback. This argument is populated internally by webhook aware plugins, such as ECSCM.

Argument Type: String

Positional arguments

projectName

Response

The new job ID.

ec-perl

syntax: $cmdr->runProcedure(<project name>, {<optionals>});

Example

$cmdr->runProcedure("Sample Project", {procedureName => "Delay",
   actualParameter => {actualParameterName => "Delay Time", value => 10}});
$xpath = $ec->runProcedure("BSHTest",
            {procedureName => "FakeMotoBuild",
           actualParameter => [
      {actualParameterName => "builddir", value => $cwd},
      {actualParameterName => "board", value => $board},
      {actualParameterName => "myview", value => $cwv},
      {actualParameterName => "resourcetouse",
                     value => $resourcetouse},
]});▼

ectool

syntax: ectool runProcedure <project name> [optionals]

Examples

ectool runProcedure <project name> --procedureName <procedure name>
   --scheduleName <schedule name>

ectool runProcedure "Sample Project" --procedureName "Delay"
   --actualParameter "Delay Time=10"▼

Back to top

setJobName

Sets the name of a running job.

You must specify jobId and newName.

Notes:

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	Descriptions
jobId	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. Argument type: UUID
newName	New name of the job. Argument type: String

Arguments

Descriptions

jobId

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.

Argument type: UUID

newName

New name of the job.

Argument type: String

Positional arguments

jobId, newName

Response

None or a status OK message.

ec-perl

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

Examples

$cmdr->setJobName(4fa765dd-73f1-11e3-b67e-b0a420524153, "Delay Test_541"); (from the command line)

$cmdr->setJobName("TestJob_252"); (from a step command)▼

ectool

syntax: ectool setJobName <jobId> <newName>

Examples

ectool setJobName 4fa765dd-73f1-11e3-b67e-b0a420524153 "Delay Test"_541 (from the command line)

ectool setJobName "TestJob"_252▼

Back to top

External Job APIs

CloudBees CD/RO includes a powerful built-in scheduler for both managing execution and real-time reporting for a "running" process. Most CloudBees CD/RO Installations choose to use its built-in scheduler because it is more powerful than most in-house built and other scheduling solutions.

However, there are use cases where an external scheduler may be appropriate, for example, an LSF Grid engine. Often, such systems are quite mature and may have been in use for many years. An organizations reliance on an LSF Grid system can mandate it remain as the driving scheduler. Many schedulers lack the richness in their graphical user interface, which is an area where CloudBees CD/RO excels—especially as it applies to monitoring the status of complex processes and workflows as they progress in real-time through the CloudBees CD/RO system. The CloudBees CD/RO GUI also provides powerful auditing capabilities for reviewing results of complex process runs.

External Job APIs are designed to leverage the CloudBees CD/RO GUI to display results for jobs running on external schedulers. The external scheduler can issue calls through these APIs to provide a representation of this same job within the CloudBees CD/RO Jobs page. CloudBees CD/RO users and the external scheduler can then monitor the complete integrated system through a single interface—the CloudBees CD/RO GUI.

The external system need not be a formal scheduler. In fact, even a simple script might be able to leverage the External Job Step API. For example, a build script could issue API calls at its beginning and end so the build is represented in CloudBees CD/RO as a job.

Using the API does not consume agent resources. The API simply allows for graphical representation of external jobs within CloudBees CD/RO .

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.

You must specify a jobId.

Arguments Descriptions

jobId

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.

Argument type: UUID

force

(Optional) < Boolean flag— 0|1|true|false > If true, all external steps belonging to the job will be marked "complete".

This arguments determines whether all external steps under the job should be recursively marked "complete".

If this API is called on a job launched with runProcedure, there is no effect unless force is enabled, in which case only external steps are affected.

Argument type: Boolean

outcome

(Optional) Overall outcome for a job or step:

success —The job finished successfully.
warning —The job completed with no errors, but encountered some suspicious conditions.
error —The job has finished execution with errors. If specified, the outcome overrides any previously propagated outcome value.

Argument type: JobOutcome

Positional arguments

jobId

Response

None or a status OK message.

ec-perl

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

Example

$cmdr->completeJob(1234);▼

ectool

syntax: ectool completeJob <jobId> [optionals]

Example

ectool completeJob 1234


[source,shell]▼

Back to top

completeJobStep

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

You must specify a jobStepId.

Arguments Descriptions

jobStepId

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

Argument type: UUID

evidence

(Optional) The reason for marking the job step complete.

Argument type: String

exitCode

(Optional) The exit code of a job step.

Argument type: Integer

force

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

If true, all external steps under the job should be recursively marked "complete".

If this API is called on a job launched with runProcedure, there is no effect unless force is enabled, in which case only external steps are affected.

Argument type: Boolean

outcome

(Optional) Overall outcome for a job or step:

success —The job step finished successfully.
warning —The job step completed with no errors, but encountered some suspicious conditions.
error —The job step has finished execution with errors.
skipped —The job step was skipped.

Argument type: JobOutcome

Positional arguments

jobStepId

Response

None or a status OK message.

ec-perl

syntax: $cmdr->completeJobStep(<jobStepId>);

Example

$cmdr->completeJobStep(5da765dd-73f1-11e3-b67e-b0a420524153);▼

ectool

syntax: ectool completeJobStep <jobStepId>

Example

ectool completeJobStep 5da765dd-73f1-11e3-b67e-b0a420524153▼

Back to top

createJob

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

You must specify projectName or destinationProject.

Arguments Descriptions

Arguments	Descriptions
projectName	The name of the project where this job will reside. You must have modify permission on the destination project. `projectName` or `destinationProject` must be specified to determine the project where the job is created. If both are specified, `destinationProject` is preferred. Argument type: String
destinationProject	If specified, determines the project where the job will reside. You must have modify permission on the destination project. `projectName` or `destinationProject` must be specified to determine the project where the job is created, `destinationProject` is preferred. Argument type: String
jobNameTemplate	If specified, the job name will be generated by expanding this argument value. The job name is generated by expanding the `jobNameTemplate` argument or the `jobNameTemplate` from the procedure or the system default. Argument type: String
procedureName	If specified, `projectName` and `procedureName` are used as a template for the job. You must have execute permission on the procedure. The job name is generated by expanding the `jobNameTemplate` argument or the `jobNameTemplate` from the specified procedure or the system default. Argument type: String
status	The starting status for the job: `pending\|runnable\|scheduled\|running>`. The `status` argument determines the "starting" job status. This is useful if you want to immediately go into a specific status without having to use `modifyJob` to update the status. Defaults to `pending`. Possible values for `status` : `pending` —The job is not yet runnable. `runnable` —The job is ready to run. `scheduled` —The job is scheduled to run. `running` —The job is executing. Argument type: JobStatus

projectName

The name of the project where this job will reside. You must have modify permission on the destination project. projectName or destinationProject must be specified to determine the project where the job is created. If both are specified, destinationProject is preferred.

Argument type: String

destinationProject

If specified, determines the project where the job will reside. You must have modify permission on the destination project. projectName or destinationProject must be specified to determine the project where the job is created, destinationProject is preferred.

Argument type: String

jobNameTemplate

If specified, the job name will be generated by expanding this argument value. The job name is generated by expanding the jobNameTemplate argument or the jobNameTemplate from the procedure or the system default.

Argument type: String

procedureName

If specified, projectName and procedureName are used as a template for the job. You must have execute permission on the procedure. The job name is generated by expanding the jobNameTemplate argument or the jobNameTemplate from the specified procedure or the system default.

Argument type: String

status

The starting status for the job: pending|runnable|scheduled|running>. The status argument determines the "starting" job status. This is useful if you want to immediately go into a specific status without having to use modifyJob to update the status. Defaults to pending. Possible values for status :

pending —The job is not yet runnable.
runnable —The job is ready to run.
scheduled —The job is scheduled to run.
running —The job is executing.

Argument type: JobStatus

Positional arguments

projectName or destinationProject

Response

The new job ID.

ec-perl

syntax: $cmdr->createJob(<projectName or destinationProject>, {<optionals>});

Example

$cmdr->createJob(projectName => "Default", {status => "Scheduled"});▼

ectool

syntax: ectool createJob <projectName or destinationProject> [optionals]

Example

ectool createJob "Default" --status "Scheduled"▼

Back to top

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 "external" is set).

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 Descriptions

actualParameter

Specifies the values to pass as parameters to the called procedure. Each parameter value is specified with an actualParameterName and a value. The actualParameterName must match the name of a formal parameter on the called procedure.

For more information about parameters, see createActualParameter .

Argument type: Map

alwaysRun

If set to 1, indicates this job step will run even if the job is aborted before the job step completes. A useful argument for running a "cleanup" step that should run whether the job step is successful or not. The value for alwaysRun is a < Boolean flag - 0|1|true|false >. Defaults to "false".

Argument type: Boolean

broadcast

Use this flag to run the same job step on several resources at the same time. The job step is "broadcast" to all resources listed in the resourceName argument. The broadcast value = < Boolean flag - 0|1|true|false >. This argument is applicable only to command job steps. Defaults to "false".

Argument type: Boolean

command

The command to run. This argument is applicable to command job steps only.

Argument type: String

comment

The script to execute the functions in this step, which are passed to the step’s shell for execution.

Argument type: String

condition

If empty or non-zero, the job step will run. If set to "0", the job step is skipped. A useful setting during procedure development or when re-running a job that has already completed some of the job steps. Also, this argument is useful for conditional execution of steps based on properties set by earlier steps.

Argument type: String

credentialName

The credential to use for impersonation on the agent. credentialName can be one of two forms: relative (for example, "cred1" )—the credential is assumed to be in the project that contains the request target object. absolute (for example, "/projects/BuildProject/credentials/cred1" )—the credential can be from any specified project, regardless of the target object’s project.

Argument type: String

credentials

Refers to one or more credentials to attach to this job step. These are dynamic credentials, captured when a job is created. Dynamic credentials are stored on the server temporarily until the job completes and then discarded. For more information about credentials, see Credentials and User Impersonation.

Argument type: Collection

credentialReferenceParameter

(Optional) Used when the procedure defines one or more credential reference parameters, that is, a parameter that references a credential from an external credential provider.

[<credName>=<externalCredential> [<credName>=<externalCredential> …]]

For local parameters, use --credentials.

Argument type: Map

description

A plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. The only HTML tags allowed in the text are: <a> <b> <br> <div> <dl> <font> <i> <li> <ol> <p> <pre> <span> <style> <table> <tc> <td> <th> <tr> <ul>

Argument type: String

errorHandling

Determines what happens to the procedure if the step fails:

failProcedure —The current procedure continues, but the overall status is error (default).
abortProcedure —Aborts the current procedure, but allows already-running steps in the current procedure to complete.
abortProcedureNow —Aborts the current procedure and terminates running steps in the current procedure.
abortJob —Aborts the entire job, terminates running steps, but allows alwaysRun steps to run.
abortJobNow —Aborts the entire job and terminates all running steps, including alwaysRun steps.
ignore —Continues as if the step succeeded.

Argument type: ErrorHandling

exclusive

< Boolean flag - 0|1|true|false >

If set to 1 or true, this job step should acquire and retain this resource exclusively. The default is 0 or false.

Setting exclusive sets exclusiveMode to "job".

Argument type: Boolean

exclusiveMode

Determines the mode to use when the step acquires a resource. Possible modes include:

none: the default behavior for the step applies.
job: retain resource for the exclusive use of this job.
step: retain resource for the exclusive use of this step and procedure it may call.
call: retain resource for the exclusive use of all steps within the current procedure call.

If you set exclusiveMode to job, or call for a resource, and hold onto that resource using the releaseMode flag set to none, then any subsequent steps that use exclusiveMode on that same resource in this job must use the same exclusiveMode setting that was used previously. For example, if you use exclusiveMode=job and releaseMode=none for a resource in one step and then, in a subsequent step use exclusiveMode=step for that same resource, the job step does not proceed. The correct setting for the subsequent step is exclusiveMode=job since that is the exclusiveMode flag setting used in the previous step.

If you set exclusiveMode to job, or call for a resource, the resource is held for the exclusive use of all the steps in the job or in the current procedure call based on the exclusiveMode setting. The resource is released:

At the completion of the job or the procedure call based on the exclusiveMode setting.
By setting releaseMode flag to release.

While the resource is being held for the exclusive use of the job or the current procedure call, then any subsequent steps that use exclusiveMode on that same resource in this job must use the same exclusiveMode setting that was used previously. For example, do not use exclusiveMode=job for a resource in one step, and in a subsequent step use exclusiveMode=step for that same resource, unless you have already released that resource using the releaseExclusive=true flag in the earlier step. A valid setting for the subsequent step would be to not set the exclusiveMode flag at all since the resource is already available for the exclusive use of the steps in the job.

Argument type: ExclusiveMode

external

If set, indicates this job step is an external step. CloudBees CD/RO will not schedule or run agent commands for external steps, but instead, represents a step managed outside of CloudBees CD/RO .

The typical usage is with an external Job (see createJob ). The status of an external job step is set using modifyJobStep, and it can be completed using completeJobStep.

The value for external is a < Boolean flag— 0|1|true|false >. Default is "false".

Argument type: Boolean

jobStepId

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

You can specify parentPath or jobStepId or both. If you specify both parentPath and jobStepId, parentPath is preferred.

Argument type: UUID

jobStepName

The name of the new dynamic job step to create.

Argument type: String

logFileName

A custom log file name produced by running the job step. By default, CloudBees CD/RO assigns a unique name for this file.

Argument type: String

parallel

< Boolean flag - 0|1|true|false >

If set to 1 or true, this job step should run at the same time as adjacent job steps marked to run as parallel. The default is 0 or false.

Argument type: Boolean

parentPath

The path of the parent job step. This argument determines the parent job for the new jobStep. The new jobStep is executed in context of the parent job step.

You can specify parentPath or jobStepId or both. If you specify both parentPath and jobStepId, parentPath is preferred.

Argument type: String

postProcessor

The name of a program to run after a job step completes. This program looks at the job step output to find errors and warnings. CloudBees CD/RO includes a customizable program called "postp" for this purpose. The value for postProcessor is a command string for invoking a post-processor program in the platform shell for the resource ( cmd for Windows, sh for UNIX).

Argument type: String

precondition

The precondition property (if it exists) is copied to the job step when the step is created. When the job step is eligible to transition from pending to runnable, the precondition is evaluated. If the precondition result is empty, false, or " 0", the step remains in the pending state. Any other value allows the step to proceed to the runnable state.

A precondition property allows steps to be created with "pause", which then pauses the procedure. In a paused state, all currently running steps continue, but no additional steps will start.

Set this property to make a step wait until one or more dependent conditions are met. When a job step is eligible to transition from pending to runnable, a precondition is evaluated.

A precondition is fixed text or text embedding a property reference that is evaluated to TRUE or FALSE. An empty string, a \"0\" or \"false\" is interpreted as FALSE. Any other result string is interpreted as TRUE. The step will block until the precondition is TRUE.

Argument type: String

For example, assume that we defined these four steps:

Build object files and executables
Build installer
Run unit tests
Install bits on test system
- Step 1 is an ordinary serial step.
- Steps 2 and 3 can run in parallel because they depend only on step 1’s completion.
- Step 4 depends on step 2, but not step 3.

You can achieve optimal step execution order with preconditions:

Make steps 2-4 run in parallel.
Step 2 needs a job property set at the end of its step to indicate step 2 is completing ( /myJob/buildInstallerCompleted=1 ).
Set a precondition in step 4: $[/myJob/buildInstallerCompleted]

procedureName

The name of the procedure for an existing step definition that will be copied to the new job step.

Argument type: String

projectName

The name of the project for an existing step definition that will be copied to the new job step.

Argument type: String

releaseExclusive

< Boolean flag— 0|1|true|false >

Declares whether or not this job step will release its resource, which is currently held "exclusively". Setting this flag to "true" is the same as setting releaseMode to release.

Argument type: Boolean

releaseMode

Use one of the following options:

none —The "default"—No action if the resource was not previously marked as "retain."
release —Releases the resource at the end of this job step. If the resource for the job step was previously acquired with "Retain exclusive" (either by this job step or some preceding job step), the resource exclusivity is canceled at the end of this job step. The resource is released in the normal way so it may be acquired by other jobs.
releaseToJob —Allows a job step to promote a "step exclusive" resource to a Job exclusive resource.

Argument type: ReleaseMode

resourceName

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

Argument type: String

shell

Where shell is the name of a program used to execute commands contained in the "command" field. The name of a temporary file containing commands will be appended to the end of this invocation line. Normally, this file is a command shell, but it can be any other command line program. The default is to use the standard shell for the platform it runs on ( cmd for Windows, sh for UNIX).

Applicable to command steps only.

Argument type: String

status

<pending|runnable|scheduled|running> The status argument determines the "starting" job status. This is useful if you want to immediately go into a specific status without having to use modifyJobStep to update the status. Defaults to pending. Possible values for status :

pending —The job step is not yet runnable.
runnable —The job step is ready to run.
scheduled —The job step is scheduled to run.
running —The job step is executing.

Argument type: JobStatus

stepName

Takes the name of an existing step and creates a job step from this definition. It is used in conjunction with procedureName and projectName and defaults to the current job’s procedure if neither are specified.

If you use stepName, createJobStep uses the existing step as a template for the new dynamic JobStep. If you use this argument, you cannot use the command argument.

You can use any project, procedure, or step as a template. If you do not provide a template, you must set the parameters of the new JobStep (such as command ) manually.

subprocedure

The name of the nested procedure to call when this job step runs. If a subprocedure is specified, do not include the command or commandFile options.

Argument type: String

subproject

If a subprocedure argument is used, this is the name of the project where that subprocedure is found. By default, the current project is used.

Argument type: String

timeLimit

The maximum length of time the job step is allowed to run. After the time specified, the job step will be aborted. The time limit is specified in units that can be hours, minutes, or seconds.

Argument type: String

timeLimitUnits

Specify hours|minutes|seconds for time limit units.

Argument type: TimeLimitUnits

workingDirectory

The CloudBees CD/RO agent sets this directory as the “current working directory,” when running the command contained in the job step. If no working directory is specified in the job step, CloudBees CD/RO uses the directory it created for the job in the CloudBees CD/RO workspace as the working directory.

If running a job step on a proxy resource, this directory must exist on the proxy target.

Argument type: String

workspaceName

The name of the workspace where the job step log files will be stored.

Argument type: String

If no workspace is specified, the created job step may default to its parent job step’s workspace. If you want the job step to use the workspace of the resource that it should run on, you must use this argument so that the workspace defaults to the workspace value indicated in the resource.

Argument type: String

The syntax for this argument is as follows:

ec-perl: '$'."[/myResource/workspaceName]"

ectool: "$"[/myResource/workspaceName]

Positional arguments

jobStepId or parentPath

Response

Returns a jobStep object.

ec-perl

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

Examples

$cmdr->createJobStep ({parentPath => "/jobs/123", external => "1"});

$cmdr->createJobStep ({jobStepId => "5da765dd-73f1-11e3-b67e-b0a420524153", external => "1"});

$cmdr->createJobStep ({jobStepId => "5da765dd-73f1-11e3-b67e-b0a420524153", workspaceName => "workspaceA"});

$cmdr->createJobStep ({jobStepId => "5da765dd-73f1-11e3-b67e-b0a420524153", workspaceName => "\$" . "[/myResource/workspaceName]"});▼

# Create a job step that calls a subprocedure and passes a parameter credential
# ‘coolProcedure’ is a procedure within the Default project with one parameter
# credential named ‘sshCredentialParameter’.

$cmdr->createJobStep(
    {
         projectName => 'Default',
        subprocedure => 'coolProcedure',
     actualParameter => [
        {
           actualParameterName => 'sshCredentialParameter',
           value => 'sshCredentialParameter'
        }
    ],
    credential => [
        {
            credentialName => 'sshCredentialParameter',
                  userName => 'sshUser',
                  password => 'super_secure_sshPassword'
        }

    ]
  }
);


# Create two parallel job steps and send them to the {PRODUCT}  server using the batch API.

# Create the batch API object
my $batch = $ec->newBatch('parallel');

# Create multiple requests
my @reqIds = (
    $batch->createJobStep(
        {
            parallel        => '1',
            projectName     => 'Default',
            subprocedure    => 'coolProcedure',
            actualParameter => [
                 {
                      actualParameterName => 'input',
                           value          => 'helloWorld'
                 }
             ],
         }
    ),
    $batch->createJobStep(
         {
             parallel        => '1',
             projectName     => 'Default',
             subprocedure    => 'coolProcedure',
             actualParameter => [
                  {
                      actualParameterName => 'input',
                            value         => 'helloWorld'
                  }
             ],
         }
     ),
);

# Send off the requests
$batch->submit();▼

ectool

syntax: ectool createJobStep [optionals]

Examples

ectool createJobStep --parentPath /jobs/123 --external 1

ectool createJobStep --jobStepId 5da765dd-73f1-11e3-b67e-b0a420524153 --external 1▼

ectool createJobStep --parallel 1 --projectName Default --subprocedure▼

coolProcedure --actualParameter input=helloWorld▼

ectool createJobStep --jobStepName "Echo-Middle" --workspaceName "workspaceA"▼

Back to top

modifyJob

Modifies the status of an externally managed job.

You must specify a jobId.

Arguments Descriptions

Arguments	Descriptions
jobId	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. Argument type: UUID
status	(Optional) `<pending\|runnable\|scheduled\|running>` This argument determines the current status of the job, and also sets related timing values. Possible values for `status` : `pending` —The job is not yet runnable. `runnable` —The job is ready to run. `scheduled` —The job is scheduled to run. `running` —The job is executing. Argument type: JobStatus

jobId

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.

Argument type: UUID

status

(Optional) <pending|runnable|scheduled|running>

This argument determines the current status of the job, and also sets related timing values. Possible values for status :

pending —The job is not yet runnable.
runnable —The job is ready to run.
scheduled —The job is scheduled to run.
running —The job is executing.

Argument type: JobStatus

Positional arguments

jobId

Response

The jobId element.

ec-perl

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

Example

cmdr->modifyJob ("4fa765dd-73f1-11e3-b67e-b0a420524153", {status => "running"});▼

ectool

syntax: ectool modifyJob <jobId> [optionals]

Example

ectool modifyJob 4fa765dd-73f1-11e3-b67e-b0a420524153 --status "running"▼

Back to top

modifyJobStep

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

You must specify a jobStepId.

Arguments Descriptions

Arguments	Descriptions
jobStepId	The unique CloudBees CD/RO -generated identifier (a UUID) for a job step that is assigned automatically when the job step is created. The system also accepts a job step name assigned to the job step by its name template. Argument type: UUID
status	(Optional) `<pending\|runnable\|scheduled\|running`. This determines the “starting” job status. This is useful if you want to immediately go into a specific status without having to use `modifyJobStep` to update the status. The default is `pending`. Possible values for `status` : `pending` –The job step is not yet runnable. `runnable` –The job step is ready to run. `scheduled` –The job step is scheduled to run. `running` –The job step is executing. Argument type: JobStatus

jobStepId

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

Argument type: UUID

status

(Optional) <pending|runnable|scheduled|running. This determines the “starting” job status. This is useful if you want to immediately go into a specific status without having to use modifyJobStep to update the status. The default is pending. Possible values for status :

pending –The job step is not yet runnable.
runnable –The job step is ready to run.
scheduled –The job step is scheduled to run.
running –The job step is executing.

Argument type: JobStatus

Positional arguments

jobStepId

Response

Returns a modified jobStep object.

ec-perl

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

Example

$cmdr->modifyJobStep ("4fa765dd-73f1-11e3-b67e-b0a420524153", {status => "running"});▼

ectool

syntax: ectool modifyJobStep <jobStepId> [optionals]

Example

ectool modifyJobStep 4fa765dd-73f1-11e3-b67e-b0a420524153 --status "running"▼

Back to top

waitForJob

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

This command works only with ec-perl.

Arguments	Descriptions
jobId	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. Argument type: UUID
timeout	(Optional) The number of seconds to wait before giving up on a request. The default is 60 seconds. Argument type: Integer
finalStatus	(Optional) The status to wait for. Must be either "running" or "completed" (the default is "completed"). Argument type: String

Arguments

Descriptions

jobId

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.

Argument type: UUID

timeout

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

The default is 60 seconds.

Argument type: Integer

finalStatus

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

Argument type: String

Positional arguments

jobId

Response

Returns the result from the final getJobStatus query.

ec-perl

syntax: $cmdr->waitForJob(<jobId>, <timeout>, <finalStatus>, {<optionals>});

Examples

Wait for a job until it has a status of completed . This call would wait for 60 seconds, which is the default timeout:

$cmdr->waitForJob("4fa765dd-73f1-11e3-b67e-b0a420524153");▼

Wait for a job until it has a status of completed . This call would wait for 30 seconds.:

$cmdr->waitForJob("4fa765dd-73f1-11e3-b67e-b0a420524153", 30);▼

Wait for a job until it has a status of running . This call would wait for 60 seconds, which is the default timeout:

$cmdr->waitForJob("4fa765dd-73f1-11e3-b67e-b0a420524153", undef, "running");▼

Back to top