Artifact Management Commands

addDependentsToArtifactVersion

Adds an artifact version query to an existing artifact. Dependent artifact versions are retrieved when the parent artifact version is retrieved.

You must specify an artifactVersionName.

Arguments Descriptions

Arguments	Descriptions
`artifactVersionName`	The name of the artifact version. An artifact version name is interpreted by the server as the `artifactVersionName` attribute for the `artifactVersion` in question. This name is parsed and interpreted as `"groupId:artifactKey:version"` and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly. Argument type: String
`dependentArtifactVersions`	(Optional) One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: `<groupId>:<artifactKey>:<versionRange>` ( `versionRange` is optional). The version range syntax is standard number interval notation. `()` marks exclusive ranges and `[]` marks inclusive ranges. Argument type: Collection

artifactVersionName

The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

dependentArtifactVersions

(Optional) One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: <groupId>:<artifactKey>:<versionRange> ( versionRange is optional). The version range syntax is standard number interval notation. () marks exclusive ranges and [] marks inclusive ranges.

Argument type: Collection

Positional arguments

artifactVersionName

Response

Returns one or more dependent artifact versions.

ec-perl

syntax: $cmdr->addDependentsToArtifactVersion (<artifactVersionName>, {<optionals>});

Example

# Add a dependency on cmdr:SDK:1.2.0 and the most current version of core:infra that
# is greater than or equal to 2.1.0.▼

$cmdr->addDependentsToArtifactVersion (artifactVersionName => "myGroup:myAKey:1.0.0-55",{dependentArtifactVersions => ["cmdr:SDK:1.2.0", "core:infra:[2.1.0,]"]});▼

ectool

syntax: ectool addDependentsToArtifactVersion <artifactVersionName> [optionals]

Example

ectool addDependentsToArtifactVersion "myGroup:myAKey:1.0.0-55"
   --dependentArtifactVersions "cmdr:SDK:1.2.0" "core:infra:[2.1.0,]"▼

Back to top

cleanupArtifactCache

Deletes stale artifact versions from an artifact cache. A "stale artifact version" is one whose metadata was previously deleted from the CloudBees CD/RO server.

If you are not logged in as "admin", you cannot use this command. However, using the force option overrides admin login privileges.

You must specify a cacheDirectory.

Arguments Descriptions

Arguments	Descriptions
cacheDirectory	The directory where stale artifact versions are stored. Argument type: String
force	< Boolean flag— `0\|1\|true\|false` > If set to "true", this option can be used so you can cleanup the artifact cache if you are not logged in as "admin". Argument type: Boolean

cacheDirectory

The directory where stale artifact versions are stored.

Argument type: String

force

< Boolean flag— 0|1|true|false > If set to "true", this option can be used so you can cleanup the artifact cache if you are not logged in as "admin".

Argument type: Boolean

Positional arguments

cacheDirectory

Response

Returns a list of directories that were deleted.

ec-perl

syntax: $cmdr->cleanupArtifactCache(<cacheDirectory>);

Example

$cmdr->cleanupArtifactCache("/var/artifact-cache");▼

ectool

syntax: ectool cleanupArtifactCache <cacheDirectory>

Example

ectool cleanupArtifactCache "/var/artifact-cache"▼

Back to top

cleanupRepository

Deletes stale artifact versions from the repository backing-store. A "stale artifact version" is one whose metadata was previously deleted from the CloudBees CD/RO server.

If you are not logged in as "admin", you cannot use this command. However, using the force option overrides admin login privileges.

You must specify a backingStoreDirectory.

Arguments Descriptions

Arguments	Descriptions
backingStoreDirectory	The repository directory where artifact versions are stored. Argument type: String
force	< Boolean flag— `0\|1\|true\|false` > If set to "true", this option can be used so you can cleanup the repository even if the g/a/v s in the directory specified do not match up with any artifacts reported by the server. By default, this is false, and helps users avoid deleting arbitrary directory trees if they did not specify the repository backing store properly. Argument type:Boolean

backingStoreDirectory

The repository directory where artifact versions are stored.

Argument type: String

force

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

If set to "true", this option can be used so you can cleanup the repository even if the g/a/v s in the directory specified do not match up with any artifacts reported by the server. By default, this is false, and helps users avoid deleting arbitrary directory trees if they did not specify the repository backing store properly.

Argument type:Boolean

Positional arguments

backingStoreDirectory

Response

Returns a list of directories that were deleted.

ec-perl

syntax: $cmdr->cleanupRepository(<backingStoreDirectory>);

Example

use strict;
use ElectricCommander;

my $cmdr = ElectricCommander->new({debug => 1});
$cmdr->login("admin", "changeme");
$cmdr->cleanupRepository("/var/repository-data");▼

ectool

syntax: ectool cleanupRepository <backingStoreDirectory>

Example

ectool cleanupRepository "/var/repository-data"▼

Back to top

createArtifact

Creates a new artifact.

You must specify groupId and artifactKey.

Arguments Descriptions

Arguments	Descriptions
groupId	A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods. Argument type: String
artifactKey	A user-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
artifactVersionNameTemplate	(Optional) A template for the names of artifact versions published to this artifact. This option overrides the value set in the server settings for "artifact name template." The global setting can be manipulated in the Server Settings page (Go to Administration > Server, and select the Settings link). Argument type: String
description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>` ▼ renders as follows: `<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.` ▼ Argument type: String

groupId

A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods.

Argument type: String

artifactKey

A user-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

artifactVersionNameTemplate

(Optional) A template for the names of artifact versions published to this artifact. This option overrides the value set in the server settings for "artifact name template." The global setting can be manipulated in the Server Settings page (Go to Administration > Server, and select the Settings link).

Argument type: String

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

Positional arguments

groupId, artifactKey

Response

Returns an artifact element.

ec-perl

syntax: $cmdr->createArtifact(<groupId>, <artifactKey>, {<optionals>});

Example

$cmdr->createArtifact("thirdPartyTools", "SDK", {description => "3rd party tools SDK"});▼

ectool

syntax: ectool createArtifact <groupId> <artifactKey> [optionals]

Example

ectool createArtifact "thirdPartyTools" "SDK" --description "3rd party tools SDK"▼

Back to top

createArtifactVersion

Creates a new artifact version.

You must specify version.

Arguments Descriptions

Arguments	Descriptions
version	The version component of the GAV ( `groupId` / `artifactVersionId` / `version` ) coordinates. Argument type: String
artifactKey	(Optional) A user-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
artifactName	(Optional) The name of the artifact. Argument type: String
dependentArtifactVersions	(Optional) The set of artifact versions on which this `artifactVersion` depends. Argument type: Collection
description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>` ▼ renders as follows: `<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.` ▼ Argument type: String
groupId	(Optional) The `groupId` component of the GAV ( `groupId` / `artifactVersionId` / `version` ) coordinates. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods. Argument type: String
jobStepId	(Optional) The unique identifier for the job step that is used to make a project association. Argument type: UUID
repositoryName	(Optional) The name of the artifact repository. Argument type: String

version

The version component of the GAV ( groupId / artifactVersionId / version ) coordinates.

Argument type: String

artifactKey

(Optional) A user-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

artifactName

(Optional) The name of the artifact.

Argument type: String

dependentArtifactVersions

(Optional) The set of artifact versions on which this artifactVersion depends.

Argument type: Collection

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

groupId

(Optional) The groupId component of the GAV ( groupId / artifactVersionId / version ) coordinates. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods.

Argument type: String

jobStepId

(Optional) The unique identifier for the job step that is used to make a project association.

Argument type: UUID

repositoryName

(Optional) The name of the artifact repository.

Argument type: String

Positional arguments

version

Response

Returns an artifactVersion element.

ec-perl

syntax: $cmdr->createArtifactVersion(<version>, {<optionals>});

Examples

$cmdr->createArtifactVersion(1.1, {artifactName => test:test1});▼

$cmdr->createArtifactVersion(1.2, {artifactName => test1:test2});▼

ectool

syntax: ectool createArtifactVersion <version> [optionals]

Examples

ectool createArtifactVersion 1.1 --artifactName test:test1▼

ectool createArtifactVersion 1.2 --artifactName test1:test2▼

Back to top

createRepository

Creates a repository for one or more artifacts.

You must specify a repositoryName.

Arguments Descriptions

Arguments	Descriptions
repositoryName	The name of the artifact repository. Argument type: String
description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>` ▼ renders as follows: `<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.` ▼ Argument type: String
repositoryDisabled	(Optional) < Boolean flag - `0\|1\|true\|false` > – When the value is `1` or `true`, the repository is disabled. The default is `0` or `false`. Argument type: Boolean
url	The URL to use to communicate with the repository server. Argument type: String
zoneName	The name of the zone where this repository resides. Argument type: String

repositoryName

The name of the artifact repository.

Argument type: String

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

repositoryDisabled

(Optional) < Boolean flag - 0|1|true|false > – When the value is 1 or true, the repository is disabled. The default is 0 or false.

Argument type: Boolean

url

The URL to use to communicate with the repository server.

Argument type: String

zoneName

The name of the zone where this repository resides.

Argument type: String

Positional arguments

repositoryName

Response

Returns a repository element.

ec-perl

syntax: $cmdr->createRepository(<repositoryName>, {<optionals>});

Example

$cmdr->createRepository("myRepos", {repositoryDisabled => "true", url =>
   "https://test.ecloud.com:8200"});▼

ectool

syntax: ectool createRepository <repositoryName> [optionals]

Example

ectool createRepository myRepos --repositoryDisabled "true" --url
   "https://test.ecloud.com:8200"▼

Back to top

deleteArtifact

Deletes an existing artifact element and all artifact versions.

You must specify an artifactName.

Arguments	Descriptions
artifactName	The name of the artifact to delete. Argument type: String

Arguments

Descriptions

artifactName

The name of the artifact to delete.

Argument type: String

Positional arguments

artifactName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteArtifact(<artifactName>);

Example

$cmdr->deleteArtifact("{PRODUCT} :SDK");▼

ectool

syntax: ectool deleteArtifact <artifactName>

Example

ectool deleteArtifact "{PRODUCT} :SDK"▼

Back to top

deleteArtifactVersion

Deletes artifact version metadata from the CloudBees CD/RO database. (This API call does not delete or remove artifacts stored on the repository machine.)

You must specify an artifactVersionName.

Arguments Descriptions

Arguments	Descriptions
artifactVersionName	The name of the artifact version. An artifact version name is interpreted by the server as the `artifactVersionName` attribute for the `artifactVersion` in question. This name is parsed and interpreted as `"groupId:artifactKey:version"` and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly. Argument type: String

artifactVersionName

The name of the artifact version. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets the name form correctly.

Argument type: String

Positional arguments

artifactVersionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteArtifactVersion(<artifactVersionName>);

Example

$cmdr->deleteArtifactVersion("myGroup:myKey:1.0.0-55");▼

ectool

syntax: ectool deleteArtifactVersion <artifactVersionName>

Example

ectool deleteArtifactVersion "myGroup:myKey:1.00.0-55"▼

Back to top

deleteRepository

Deletes artifact repository metadata from the CloudBees CD/RO database. (This API call does not delete or remove artifacts stored on the repository machine.)

You must enter a repositoryName.

Arguments	Descriptions
repositoryName	The name of the artifact repository. Argument type: String

Arguments

Descriptions

repositoryName

The name of the artifact repository.

Argument type: String

Positional arguments

repositoryName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->deleteRepository(<repositoryName>);

Example

$cmdr->deleteRepository ("cmdrReposOne");▼

ectool

syntax: ectool deleteRepository <repositoryName>

Example

ectool deleteRepository "cmdrReposOne"▼

Back to top

findArtifactVersions

This command returns the most current artifact version that matches the filter criteria and its dependent artifact versions. This API implicitly searches for artifact versions in the "available" state, and if run in a job step, registers the step as a retriever for the returned artifact versions.

Because of the complexity of specifying filter criteria, this API is not supported by ectool . However, all of its capabilities are supported through the Perl API.

The retrieveArtifactVersions API uses this API to find the appropriate artifact version in the CloudBees CD/RO server and then retrieves the artifact version from a repository. You may prefer to use the retrieveArtifactVersions API instead of this API because while this API returns slightly different information, it also has the side-effect of "retriever step registration" mentioned above.

You must specify an artifactName or a groupId with an artifactKey.

Arguments Descriptions

Arguments	Descriptions
artifactKey	User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. This is the `artifactKey` component of the GAV ( `GroupId` / `ArtifactVersionId` / `Version` ) coordinates. Argument type: String
artifactName	The name of an artifact. Argument type: String
artifactVersionName	The name of an artifact version ( artifactVersion ). Argument type: String
filters	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 are used to select objects based on the value of the object’s intrinsic or custom property. Boolean filters ("and", "or", "not") are 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 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
groupId	A user-generated group name for this artifact. This field may consist of alphanumeric characters, spaces, underscores, hyphens, and periods. This is the `groupId` component of the GAV ( `GroupId` / `ArtifactVersionId` / `Version` ) coordinates. The default is the name of the project that owns the job step requesting the artifact when a job step makes such as request. This argument is required when there is no job step. Argument type: String
includeDependents	< Boolean flag - `0\|1\|true\|false` > Options are: `0/false` – dependent artifacts are not retrieved. `1/true` – dependent artifacts are retrieved. Argument type: Boolean
jobStepId	The unique identifier for the job step that is making the request. This job step is marked as a retriever for the matching artifact versions. Argument type: UUID
versionRange	The range of versions to search. Version range syntax is standard number interval notation. `()` marks exclusive ranges and `[]` marks inclusive ranges. Argument type: String

artifactKey

User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. This is the artifactKey component of the GAV ( GroupId / ArtifactVersionId / Version ) coordinates.

Argument type: String

artifactName

The name of an artifact.

Argument type: String

artifactVersionName

The name of an artifact version ( artifactVersion ).

Argument type: String

filters

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 are used to select objects based on the value of the object’s intrinsic or custom property.
Boolean filters ("and", "or", "not") are 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 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

groupId

A user-generated group name for this artifact. This field may consist of alphanumeric characters, spaces, underscores, hyphens, and periods.

This is the groupId component of the GAV ( GroupId / ArtifactVersionId / Version ) coordinates. The default is the name of the project that owns the job step requesting the artifact when a job step makes such as request.

This argument is required when there is no job step.

Argument type: String

includeDependents

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

Options are:

0/false – dependent artifacts are not retrieved.
1/true – dependent artifacts are retrieved.

Argument type: Boolean

jobStepId

The unique identifier for the job step that is making the request. This job step is marked as a retriever for the matching artifact versions.

Argument type: UUID

versionRange

The range of versions to search. Version range syntax is standard number interval notation. () marks exclusive ranges and [] marks inclusive ranges.

Argument type: String

Positional arguments

None

Response

Returns zero or more artifactVersion elements. In addition, this API returns a searchDetails element with text describing how the server evaluated candidate artifact versions and ultimately decided to return the result artifactVersion and its dependents.

ec-perl

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

Example 1

# Find the most current core:infra artifact version whose version is 1.x.x.
$cmdr->findArtifactVersions({groupId => "core",
                         artifactKey => "infra",
                        versionRange => "[1.0, 2.0)"});

# Or alternatively ...
$cmdr->findArtifactVersions({artifactName => "core:infra",
                             versionRange => "[1.0,2.0)"});▼

Example 2

# Find the most current core:infra artifact version with QA approval level 3 or above.
$cmdr->findArtifactVersions({groupId => "core",
                         artifactKey => "infra",
                              filter => {propertyName => "qaLevel",
                            operator => "greaterOrEqual",
                            operand1 => "3"}});▼

ectool

Not supported.

Back to top

getArtifact

Retrieves an artifact by name.

You must specify an artifactName.

Arguments	Descriptions
artifactName	The name of the artifact. Argument type: String

Arguments

Descriptions

artifactName

The name of the artifact.

Argument type: String

Positional arguments

artifactName

Response

Returns an artifact element.

ec-perl

syntax: $cmdr->getArtifact (<artifactName>);

Example

$cmdr-> getArtifact("myGroup:myKey");▼

ectool

syntax: ectool getArtifact <artifactName>

Example

ectool getArtifact "myGroup:myKey"▼

Back to top

getArtifacts

Retrieves all artifacts in the system.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None

Response

Returns zero or more artifact elements.

ec-perl

syntax: $cmdr->getArtifacts ();

Example

$cmdr->getArtifacts ();▼

ectool

syntax: ectool getArtifacts

Example

ectool getArtifacts▼

Back to top

getArtifactVersion

Retrieves an artifact version by its name.

You must specify an artifactVersionName.

Arguments Descriptions

Arguments	Descriptions
artifactVersionName	The name of the artifact version to retrieve. An artifact version name is interpreted by the server as the `artifactVersionName` attribute for the `artifactVersion` in question. This name is parsed and interpreted as `"groupId:artifactKey:version"` and the object is searched either way you specify its name. The CloudBees CD/RO server interprets either name form correctly. Argument type: String
includeRetrieverJobs	(Optional) < Boolean flag— `0\|1\|true\|false` > If set to `1` or `true`, this argument includes `jobId` and `jobName` in returned information. A retriever job is any job that has retrieved the artifact version. Argument type: Boolean
includeRetrieverJobSteps	(Optional) < Boolean flag— `0\|1\|true\|false` > If set to `1` or `true`, this argument includes `jobId`, `jobName`, and `jobStepId` information. A retriever job is any job that has retrieved the artifact version. Because there is no bound to how many job steps may retrieve a given artifact version, the server limits the response to the most recent 200 job steps. Argument type: Boolean
maxRetrievers	(Optional) If one of the `includeRetriever` * options are specified, return at most "this many" of the most recent retrievers. Without this option, the CloudBees CD/RO server will return all retrievers. Argument type: String

artifactVersionName

The name of the artifact version to retrieve. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets either name form correctly.

Argument type: String

includeRetrieverJobs

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

If set to 1 or true, this argument includes jobId and jobName in returned information. A retriever job is any job that has retrieved the artifact version.

Argument type: Boolean

includeRetrieverJobSteps

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

If set to 1 or true, this argument includes jobId, jobName, and jobStepId information. A retriever job is any job that has retrieved the artifact version. Because there is no bound to how many job steps may retrieve a given artifact version, the server limits the response to the most recent 200 job steps.

Argument type: Boolean

maxRetrievers

(Optional) If one of the includeRetriever * options are specified, return at most "this many" of the most recent retrievers. Without this option, the CloudBees CD/RO server will return all retrievers.

Argument type: String

Positional arguments

artifactVersionName

Response

Returns one artifactVersion element. If includeRetrieverJobs or includeRetrieverJobSteps is set, the artifactVersion element will contain zero or more retriever child elements, each containing retriever information for one job or job step.

ec-perl

syntax: $cmdr->getArtifactVersion(<artifactVersionName>, {<optionals>});

Example

$cmdr->getArtifactVersion("myGroup:myKey:1.0.0-55", {includeRetrieverJobs => "true"});▼

ectool

syntax: ectool getArtifactVersion <artifactVersionName> [optionals]

Example

ectool getArtifactVersion "myGroup:myKey:1.0.0-55" -–includeRetrieverJobs "true"▼

Back to top

getArtifactVersions

Retrieves all artifact versions in the system, filtered by artifact name, retriever job ID, and/or retriever job step ID.

You must specify search filter criteria to find the artifact versions you need. If you do not provide any options, all artifact versions in the system are returned.

Arguments	Descriptions
artifactName	The name of the artifact for the versions to retrieve. Argument type: String
retrieverJobId	The job ID to use when retrieving an artifact. Argument type: UUID
retrieverJobStepId	The job step ID to use when retrieving an artifact. Argument type: UUID

Arguments

Descriptions

artifactName

The name of the artifact for the versions to retrieve.

Argument type: String

retrieverJobId

The job ID to use when retrieving an artifact.

Argument type: UUID

retrieverJobStepId

The job step ID to use when retrieving an artifact.

Argument type: UUID

Positional arguments

None

Response

Returns zero or more artifactVersion elements.

ec-perl

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

Example

$cmdr->getArtifactVersions({artifactName => "myGroup:myKey"});▼

ectool

syntax: ectool getArtifactVersions [optionals]

Example

ectool getArtifactVersions --artifactName "myGroup:myKey"▼

Back to top

getManifest

Retrieves the manifest for a specified artifact version. The manifest includes a list of files and directories in the artifact version and its checksum file.

You must specify the artifactVersionName.

Arguments	Descriptions
artifactVersionName	The name of the artifact version whose manifest you want to retrieve. Argument type: String

Arguments

Descriptions

artifactVersionName

The name of the artifact version whose manifest you want to retrieve.

Argument type: String

Positional arguments

None

Response

Returns manifest information for the specified artifact version: returns an XML stream containing any number of file elements, including the file name, file size, and "sha1" hashes for every file in the artifactVersionName.

ec-perl

syntax: $cmdr->getManifest(<artifactVersionName>);

Example

my ($manifest,$diagnostics) = $cmdr\->getManifest("myGroup:myKey:1.0.0-55");▼

ectool

syntax: ectool getManifest <artifactVersionName>

Example

ectool getManifest myGroup:myKey:1.0.0-55▼

Back to top

getRepositories

Retrieves all artifact repository objects known to the CloudBees CD/RO server.

Arguments	Descriptions
None	–

Arguments

Descriptions

None

–

Positional arguments

None

Response

Returns zero or more repository elements.

ec-perl

syntax: $cmdr->getRepositories ();

Example

$cmdr->getRepositories ();▼

ectool

syntax: ectool getRepositories

Example

ectool getRepositories▼

Back to top

getRepository

Retrieves an artifact repository by its name.

You must specify a repositoryName.

Arguments	Descriptions
repositoryName	The name of the artifact repository to retrieve. Argument type: String

Arguments

Descriptions

repositoryName

The name of the artifact repository to retrieve.

Argument type: String

Positional arguments

repositoryName

Response

Returns one repository element.

ec-perl

syntax: $cmdr->getRepository(<repositoryName>);

Example

$cmdr->getRepository("myRepository");▼

ectool

syntax: ectool getRepository <repositoryName>

Example

ectool getRepository "myRepository"▼

Back to top

getRetrievedArtifacts

Retrieves artifacts during a job.

You must specify an 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
componentName	(Optional) Name of the component. Argument type: String
resourceName	(Optional) Name of the resource. 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

componentName

(Optional) Name of the component.

Argument type: String

resourceName

(Optional) Name of the resource.

Argument type: String

Positional arguments

jobId

Response

Returns retrieved artifacts from the job.

ec-perl

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

Example

$cmdr->getRetrievedArtifacts("4fa765dd-73f1-11e3-b67e-b0a420524153", {componentName => "WAR files"});▼

ectool

syntax: ectool getRetrievedArtifacts <jobId> [optionals]

Example

ectool getRetrievedArtifacts "4fa765dd-73f1-11e3-b67e-b0a420524153" --componentName "WAR files"▼

Back to top

modifyArtifact

Modifies an existing artifact.

You must specify an artifactName.

Arguments Descriptions

Arguments	Descriptions
artifactName	The name of the artifact to modify. Argument type: String
artifactVersionNameTemplate	(Optional) A template for the names of artifact versions published to this artifact. This option overrides the value set in the server settings for "artifact name template." The global setting can be manipulated in the Server Settings page (Administration > Server, select the Settings link). Argument type: String
description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>` ▼ renders as follows: `<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.` ▼ Argument type: String

artifactName

The name of the artifact to modify.

Argument type: String

artifactVersionNameTemplate

(Optional) A template for the names of artifact versions published to this artifact. This option overrides the value set in the server settings for "artifact name template." The global setting can be manipulated in the Server Settings page (Administration > Server, select the Settings link).

Argument type: String

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

Positional arguments

artifactName

Response

Returns a modified artifact element.

ec-perl

syntax: $cmdr->modifyArtifact(<artifactName>, {<optionals>});

Example

$cmdr->modifyArtifact("thirdParty-SDK", {description => "contains artifact versions for SDK"});▼

ectool

syntax: ectool modifyArtifact <artifactName> [optionals]

Example

ectool modifyArtifact "thirdParty-SDK" --description "contains artifact versions for SDK"▼

Back to top

modifyArtifactVersion

Modifies an existing artifact version.

You must specify an artifactVersionName.

Arguments Descriptions

artifactVersionName

The name of the artifact version to modify. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name. The CloudBees CD/RO server interprets either name form correctly.

Argument type: String

artifactVersionState

(Optional) The state of the artifact version. < publishing|available|unavailable >.

Argument type: ArtifactVersionState

dependentArtifactVersions

(Optional) One or more artifact version queries. The most current match for each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: <groupId>:<artifactKey>:<versionRange> (version range is optional).

The absence of this argument does not clear or modify the dependent artifact version list for this artifact version.

Argument type: Collection

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

newName

(Optional) New name for this artifact version.

Argument type: String

removeAllDependentArtifactVersions

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

The default is 0 or false where dependencies are not removed." If this argument is set to 1 or true, all dependent artifacts will be removed from this artifact version. Subsequent "retrieves" will no longer retrieve dependent artifacts for this artifact version.

Argument type: Boolean

repositoryName

(Optional) The name of the artifact repository.

Argument type: String

Positional arguments

artifactVersionName

Response

Returns a modified artifact version element.

ec-perl

syntax: $cmdr->modifyArtifactVersion(<artifactVersionName>, {<optionals>});

Example

$cmdr->modifyArtifactVersion("myGroup:myKey:1.0.1-42375", {artifactVersionState => "unavailable"});▼

ectool

syntax: ectool modifyArtifactVersion <artifactVersionName> [optionals]

Example

ectool modifyArtifactVersion "myGroup:myKey:1.0.1-57385" --artifactVersionState unavailable▼

Back to top

modifyRepository

Modifies an existing artifact repository.

You must specify a repositoryName.

Arguments Descriptions

Arguments	Descriptions
repositoryName	The name of the artifact repository. Argument type: String
description	(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with `<html> … </html>` tags. Allowable HTML tags are `<a>`, `<b>`, `<br>`, `<div>`, `<dl>`, `<font>`, `<i>`, `<li>`, `<ol>`, `<p>`, `<pre>`, `<span>`, `<style>`, `<table>`, `<tc>`, `<td>`, `<th>`, `<tr>`, and `<ul>`. For example, the following HTML: `<p> <span style="font-family: Arial;"> <i>Note:</i> For more information about the <b>abc</b> object, see <a href="https://www.google.com/">https://www.google.com</a>. </span> </p>` ▼ renders as follows: `<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.` ▼ Argument type: String
newName	(Optional) New name of the repository. Argument type: String
repositoryDisabled	(Optional) < Boolean flag— `0\|1\|true\|false` > This argument marks the repository as enabled ( `0` or `false` ) or disabled ( `1` or `true` ). If you do not specify this, the state of the repository is unchanged. Argument type: Boolean
url	(Optional) The URL used to communicate with the artifact repository. Argument type: String
zoneName	(Optional) The name of the zone where this repository resides. Argument type: String

repositoryName

The name of the artifact repository.

Argument type: String

description

(Optional) Plain text or HTML description for this object. If using HTML, you must surround your text with <html> … </html> tags. Allowable HTML tags are <a>, <b>, <br>, <div>, <dl>, <font>, <i>, <li>, <ol>, <p>, <pre>, <span>, <style>, <table>, <tc>, <td>, <th>, <tr>, and <ul>.

For example, the following HTML:

<p>
<span style="font-family: Arial;">
  <i>Note:</i> For more information about the <b>abc</b> object, see
         <a href="https://www.google.com/">https://www.google.com</a>.
</span>
</p>▼

renders as follows:

<i>Note</i>: For more information about the <b>abc</b> object, see https://www.google.com.▼

Argument type: String

newName

(Optional) New name of the repository.

Argument type: String

repositoryDisabled

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

This argument marks the repository as enabled ( 0 or false ) or disabled ( 1 or true ). If you do not specify this, the state of the repository is unchanged.

Argument type: Boolean

url

(Optional) The URL used to communicate with the artifact repository.

Argument type: String

zoneName

(Optional) The name of the zone where this repository resides.

Argument type: String

Positional arguments

repositoryName

Response

Returns a modified repository element.

ec-perl

syntax: $cmdr->modifyRepository (<repositoryName>, {<optionals>});

Example

$cmdr->modifyRepository("cmdrRepository", {newName => "flowRepository"});▼

ectool

syntax: ectool modifyRepository <repositoryName> [optionals]

Example

ectool modifyRepository "cmdrRepository" --newName "flowRepository"▼

Back to top

moveRepository

Moves an artifact repository in front of another, specified repository or to the end of the list. This API does not move artifact version data to another repository server machine. Only the repository order in which CloudBees CD/RO searches to retrieve an artifact version is changed.

You must specify a repositoryName.

Arguments Descriptions

Arguments	Descriptions
repositoryName	The name of the artifact repository you need to move. Argument type: String
beforeRepositoryName	(Optional) Moves this repository ( `repositoryName` ) to a place before the name specified by this option. If omitted, `repositoryName` is moved to the end. Argument type: String

repositoryName

The name of the artifact repository you need to move.

Argument type: String

beforeRepositoryName

(Optional) Moves this repository ( repositoryName ) to a place before the name specified by this option. If omitted, repositoryName is moved to the end.

Argument type: String

Positional arguments

repositoryName

Response

Returns a modified repository element or an error if the repository does not exist.

ec-perl

syntax: $cmdr->moveRepository(<repositoryName>, {<optionals>});

Example

$cmdr->moveRepository("reposThree", {beforeRepositoryName => "reposOne"});▼

ectool

syntax: ectool moveRepository <repositoryName> [optionals]

Example

ectool moveRepository "reposThree" --beforeRepositoryName "reposOne"▼

Back to top

publishArtifactVersion

Publishes an artifact version to an artifact repository.

This API wraps the "publish" function in the ElectricCommander::ArtifactManagement Perl module and hides some additional functionality implemented in that module.

You must specify an artifactName or a groupId with an artifactKey.

Arguments Descriptions

Arguments	Descriptions
artifactName	The name of an artifact. Argument type: String
artifactKey	User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
compress	<Boolean flag— `0\|1\|true\|false` > Default is "true". Controls whether or not the artifact version is compressed during transport, which improves performance for cases where artifact version files are compressible, saving network bandwidth. Where artifact version files are not compressible, performance is reduced. Another consideration is that the artifact version is stored compressed/uncompressed based on this setting in the repository backing-store. Argument type: Boolean
dependentArtifactVersions	One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: `<groupId>:<artifactKey>:<versionRange>` ( `versionRange` is optional). The version range syntax is standard number interval notation. `()` marks exclusive ranges and `[]` marks inclusive ranges. Argument type: Collection
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
excludePatterns	Semi-colon delimited list of file-path patterns indicating which files/directories under `"fromDirectory"` to exclude when publishing an artifact version. Defaults to "empty," which means no files are excluded. See more information on "pattern syntax" below. Argument type: Collection
followSymlinks	<Boolean flag— `0\|1\|true\|false` > Default is "true". If true, follow symbolic links and record the target file contents with the symbolic link name in the artifact. If false, record the symbolic link as a symbolic link. Following symbolic links causes the publish API to remain compatible with previous releases. Argument type: Boolean
fromDirectory	The directory containing files to publish as the artifact version. A subset of files can be published based on `includePatterns` and `excludePatterns`. Argument type: String
groupId	A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
includePatterns	Semicolon delimited list of file-path patterns indicating which files/directories under `"fromDirectory"` to publish in the artifact version. Defaults to "empty," which means all files will be included. Conversely, if only two files are "included," no other files except those two will be included. See more information on "pattern syntax" below. Argument type: Collection
repositoryName	The name of the artifact repository where you want to publish. Argument type: String
version	Unique identifier for the artifact version in the form: `major.minor.patch-qualifier-buildNumber` `major, minor, patch`, and `buildNumber` are integers and qualifier can contain any character *except* the following: \:<>\|?*/ If a version argument is provided, but does not follow the above format, the version will be considered `0.0.0-<user-specified-version-arg>-0` implicitly. See the examples below. Argument type: String

artifactName

The name of an artifact.

Argument type: String

artifactKey

User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

compress

<Boolean flag— 0|1|true|false > Default is "true". Controls whether or not the artifact version is compressed during transport, which improves performance for cases where artifact version files are compressible, saving network bandwidth. Where artifact version files are not compressible, performance is reduced. Another consideration is that the artifact version is stored compressed/uncompressed based on this setting in the repository backing-store.

Argument type: Boolean

dependentArtifactVersions

One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: <groupId>:<artifactKey>:<versionRange> ( versionRange is optional). The version range syntax is standard number interval notation. () marks exclusive ranges and [] marks inclusive ranges.

Argument type: Collection

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

excludePatterns

Semi-colon delimited list of file-path patterns indicating which files/directories under "fromDirectory" to exclude when publishing an artifact version. Defaults to "empty," which means no files are excluded. See more information on "pattern syntax" below.

Argument type: Collection

followSymlinks

Default is "true". If true, follow symbolic links and record the target file contents with the symbolic link name in the artifact. If false, record the symbolic link as a symbolic link. Following symbolic links causes the publish API to remain compatible with previous releases.

Argument type: Boolean

fromDirectory

The directory containing files to publish as the artifact version. A subset of files can be published based on includePatterns and excludePatterns.

Argument type: String

groupId

A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

includePatterns

Semicolon delimited list of file-path patterns indicating which files/directories under "fromDirectory" to publish in the artifact version. Defaults to "empty," which means all files will be included. Conversely, if only two files are "included," no other files except those two will be included. See more information on "pattern syntax" below.

Argument type: Collection

repositoryName

The name of the artifact repository where you want to publish.

Argument type: String

version

Unique identifier for the artifact version in the form: major.minor.patch-qualifier-buildNumber major, minor, patch, and buildNumber are integers and qualifier can contain any character except the following: \:<>|?*/

If a version argument is provided, but does not follow the above format, the version will be considered 0.0.0-<user-specified-version-arg>-0 implicitly. See the examples below.

Argument type: String

===Version number examples

User Input	Interpretation
User Input	Major.Minor.Patch	Qualifier	Build Number
1	1.0.0		0
1.0	1.0.0		0
1.0-frank	1.0.0	frank	0
1.0-36	1.0.0		36
1.0-frank-36	1.0.0	frank	36

===Pattern syntax

Include / exclude patterns are expressed as relative paths under the fromDirectory.

Pattern syntax and behavior is the same as Ant and uses the following wildcard specifiers:

` ?` —matches a single character

` \*` —matches any number of characters, but only at a single directory level

*\* —matches any number of directory levels

Examples:

Use \*.txt to match any .txt file in the top-level directory.

Use */\*.txt to match any .txt file in any child directory.

Use *\*/\*.txt to match any .txt file at any level.

Positional arguments

None

Response

Returns one artifactVersion element.

ec-perl

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

Example

# Add version 1.0.0-55 for artifact myGroup:myKey with a dependency on cmdr:SDK:1.2.0,
# and the most current version of core:infra that is greater than or equal to 2.1.0.
# Note: In the Perl API, the argument must be specified as singular even though it
# can take multiple values.

$cmdr->publishArtifactVersion({artifactName => "myGroup:myKey",
                                    version => "1.0.0-55",
                   dependentArtifactVersion => ["cmdr:SDK:1.2.0", "core:infra:{2.1,]"]});▼

ectool

syntax: ectool publishArtifactVersion [optionals]

Example

ectool publishArtifactVersion --artifactName "myGroup:myKey" --version "1.0.0-55"
   --dependentArtifactVersion "cmdr:SDK:1.2.0":"core:infra"▼

Back to top

removeDependentsFromArtifactVersion

Removes a list of dependent artifact versions from an existing artifact version.

You must specify the artifactVersionName.

Arguments Descriptions

Arguments	Descriptions
artifactVersionName	The name of the artifact version from which you want to remove dependents. An artifact version name is interpreted by the server as the `artifactVersionName` attribute for the `artifactVersion` in question. This name is parsed and interpreted as `"groupId:artifactKey:version"` and the object is searched either way you specify its name—the CloudBees CD/RO server interprets either name form correctly. Argument type: String
dependentArtifactVersions	(Optional) One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved. Dependent artifact version query strings are in this form: `<groupId>:<artifactKey>:<versionRange>` ( `versionRange` is optional). The version range syntax is standard number interval notation. `()` marks exclusive ranges and `[]` marks inclusive ranges. Argument type: Collection

artifactVersionName

The name of the artifact version from which you want to remove dependents. An artifact version name is interpreted by the server as the artifactVersionName attribute for the artifactVersion in question. This name is parsed and interpreted as "groupId:artifactKey:version" and the object is searched either way you specify its name—the CloudBees CD/RO server interprets either name form correctly.

Argument type: String

dependentArtifactVersions

(Optional) One or more artifact version queries. The most current match of each query is retrieved when the primary artifact is retrieved.

Dependent artifact version query strings are in this form: <groupId>:<artifactKey>:<versionRange> ( versionRange is optional).

The version range syntax is standard number interval notation. () marks exclusive ranges and [] marks inclusive ranges.

Argument type: Collection

Positional arguments

artifactVersionName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->removeDependentsFromArtifactVersion(<artifactVersionName>, {<optionals>});

Example

# Note: In the Perl API, the argument must be specified as singular
# even though it can take multiple values.

$cmdr->removeDependentsFromArtifactVersion(myGroup:myKey:1.0.0-55,
        {dependentArtifactVersion => ["cmdr:onlineHelp:1.0.0"});▼

ectool

syntax: ectool removeDependentsFromArtifactVersion <artifactVersionName> [optionals]

Example

ectool removeDependentsFromArtifactVersion myGroup:myKey:1.0.0-55
   --dependentArtifactVersions "cmdr"onlineHelp:1.0.0"▼

Back to top

resolveRoute

Resolves the network route to an artifact repository.

You must specify the toRepositoryName.

Arguments	Descriptions
toRepositoryName	Name of the artifact repository. Argument type: String
fromAgentId	(Optional) Identifier of the agent requesting the route to a destination agent or artifact repository. Argument type: Long
fromResourceName	(Optional) Name of the resource requesting the route to a destination agent or artifact repository. Argument type: String

Arguments

Descriptions

toRepositoryName

Name of the artifact repository.

Argument type: String

fromAgentId

(Optional) Identifier of the agent requesting the route to a destination agent or artifact repository.

Argument type: Long

fromResourceName

(Optional) Name of the resource requesting the route to a destination agent or artifact repository.

Argument type: String

Positional arguments

toRepositoryName

Response

None or a status OK message.

ec-perl

syntax: $cmdr->resolveRoute (<toRepositoryName>, {<optionals>});

Examples

$cmdr->resolveRoute("Web Server", {fromResourceName => "Agent 2"});▼

ectool

syntax: ectool resolveRoute <toRepositoryName> [optionals]

Example

ectool resolveRoute "Web Server" --fromResourceName "Agent 2"▼

Back to top

retrieveArtifactVersions

Retrieves the most recent artifact version, including its dependents, from an artifact repository.

This API wraps the "retrieve" function in the ElectricCommander::ArtifactManagement Perl module and hides some additional functionality implemented in that module.

You must specify search criteria options to locate the artifact versions you want to retrieve.

Arguments Descriptions

Arguments	Descriptions
artifactKey	User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
artifactName	The name of the artifact. Argument type: String
artifactVersionName	The name of the artifact version. Argument type: String
cacheDirectory	The directory where the artifact version is stored. The artifact version files are stored in a subdirectory under this cache directory. Argument type: String
filters	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. There are two types of filters: Property filters are used to select objects based on the value of the object’s intrinsic or custom property. Boolean filters ("and", "or", "not") are 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 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
groupId	A user-generated group name for this artifact. This field may consist of alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
includeDependents	<Boolean flag— `0\|1\|true\|false` > The default is `1` or `true`. If the value is `1` or `true` : The artifact and its dependents are retrieved. The published artifact version includes the artifact’s dependents, such as a list of one or more artifact versions. The dependent artifact versions are stored in a subdirectory under the `cacheDirectory` or if `toDirectory` is specified, under the `oDirectory/ec_dependent_artifacts` directory. If the value is `0` or `false`, only the artifact is retrieved. The artifact version does not include the dependent artifacts. Argument type: Boolean
overwrite	Options are: `true—deletes previous content in the directory and replaces the content with your new version.` `false—(existing behavior) if the directory does not exist, one will be created and filled with the artifact’s content. If the directory exists, a new directory is created with a unique name and the artifact contents is supplied there. ` `update` —this is similar to a merge operation—two artifact versions can be moved into the same directory, but individual files with the same name will be overwritten. Argument type: String
repositoryNames	A space-separated list of artifact repository names. Retrieval is attempted from each specified repository in a specified order until it succeeds or all specified repositories have rejected the retrieval. If not specified, and if this request is made in a job step context, a preferred list of repository names is obtained from the Resource definition in the server. If that list is empty, the global repository list is used. Argument type: String
retryNumber	Number of retry attempts for the operation. The default is 1. The time between retry attempts is 20 seconds. Argument type: Integer
toDirectory	Used to retrieve an artifact version to a specific directory without imposing the structure of a cache directory. Specify the full path to the new directory. If the artifact version is in a local cache directory. it will be copied out of the cache. If the artifact version is not in a cache directory, it will be downloaded directly to the specified directory, without putting it into a cache. `toDirectory` overrides `cacheDirectory` for downloads. Argument type: String
versionRange	The range of versions to search. Version range syntax is standard number interval notation. `()` marks exclusive ranges and `[]` marks inclusive ranges. Argument type: String

artifactKey

User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

artifactVersionName

The name of the artifact version.

Argument type: String

cacheDirectory

The directory where the artifact version is stored. The artifact version files are stored in a subdirectory under this cache directory.

Argument type: String

filters

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.

There are two types of filters:

Property filters are used to select objects based on the value of the object’s intrinsic or custom property.
Boolean filters ("and", "or", "not") are 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 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

groupId

A user-generated group name for this artifact. This field may consist of alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

includeDependents

The default is 1 or true. If the value is 1 or true :

The artifact and its dependents are retrieved.
The published artifact version includes the artifact’s dependents, such as a list of one or more artifact versions.
The dependent artifact versions are stored in a subdirectory under the cacheDirectory or if toDirectory is specified, under the oDirectory/ec_dependent_artifacts directory.

If the value is 0 or false, only the artifact is retrieved. The artifact version does not include the dependent artifacts.

Argument type: Boolean

overwrite

Options are:

true—deletes previous content in the directory and replaces the content with your new version.
`false—(existing behavior) if the directory does not exist, one will be created and filled with the artifact’s content. If the directory exists, a new directory is created with a unique name and the artifact contents is supplied there. `
update —this is similar to a merge operation—two artifact versions can be moved into the same directory, but individual files with the same name will be overwritten.

Argument type: String

repositoryNames

A space-separated list of artifact repository names. Retrieval is attempted from each specified repository in a specified order until it succeeds or all specified repositories have rejected the retrieval.

If not specified, and if this request is made in a job step context, a preferred list of repository names is obtained from the Resource definition in the server. If that list is empty, the global repository list is used.

Argument type: String

retryNumber

Number of retry attempts for the operation. The default is 1. The time between retry attempts is 20 seconds.

Argument type: Integer

toDirectory

Used to retrieve an artifact version to a specific directory without imposing the structure of a cache directory. Specify the full path to the new directory.

If the artifact version is in a local cache directory. it will be copied out of the cache.
If the artifact version is not in a cache directory, it will be downloaded directly to the specified directory, without putting it into a cache. toDirectory overrides cacheDirectory for downloads.

Argument type: String

versionRange

The range of versions to search.

Version range syntax is standard number interval notation. () marks exclusive ranges and [] marks inclusive ranges.

Argument type: String

Positional arguments

None

Response

Returns one or more artifactVersion elements.

ec-perl

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

Examples

# Retrieve the most current core:infra artifact version whose version is 1.x.x.
$cmdr->retrieveArtifactVersions({groupId => "core",
                             artifactKey => "infra",
                            versionRange => "[1.0,2.0)"});
# Or alternatively...
$cmdr->retrieveArtifactVersions({artifactName => "core:infra",
                                 versionRange => "[1.0,2.0)"});▼

ectool

syntax: ectool retrieveArtifactVersions [optionals]

Example

ectool retrieveArtifactVersions --artifactName "core:infra" --versionRange "[1.0,2.0)"▼

The filter option does not perform as expected if using ectool. If you need the filter option, write your retrieveArtifactVersions API call in ec-perl.

Back to top

updateArtifactVersion

Updates an artifact version by adding or replacing one or more files in the existing file and publishes the result as a new artifact version to an artifact repository.

This API wraps the "update" function in the ElectricCommander::ArtifactManagement Perl module and hides some additional functionality implemented in that module.

You must specify search criteria options to locate the artifact versions you want to update.

Arguments Descriptions

Arguments	Descriptions
artifactKey	User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods. Argument type: String
artifactName	The name of the artifact. Argument type: String
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
excludePatterns	Semi-colon delimited list of file-path patterns indicating which files/directories under `"fromDirectory"` to exclude when publishing an artifact version. Defaults to "empty," which means no files are excluded. See more information on "pattern syntax" below. Argument type: Collection
followSymlinks	<Boolean flag— `0\|1\|true\|false` > The default is `1` or `true`. If `1` or `true`, CloudBees CD/RO follows symbolic links and record the target file contents with the symbolic link name in the artifact. If `0` or `false`, CloudBees CD/RO records the symbolic link as a symbolic link. Following symbolic links causes the publish API to remain compatible with previous releases. Argument type: Boolean
fromDirectory	The directory containing files to publish as the artifact version. A subset of files can be published based on `includePatterns` and `excludePatterns`. Argument type: String
groupId	A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods. Argument type: String
includePatterns	Semi-colon delimited list of file-path patterns indicating which files/directories under `"fromDirectory"` to publish in the artifact version. Defaults to "empty," which means all files will be included. Conversely, if only two files are "included," no other files except those two will be included. See more information on "pattern syntax" below. Argument type: Collection
newVersion	Unique identifier for the new artifact version in the form: `major.minor.patch-qualifier-buildNumber` `major, minor, patch`, and `buildNumber` are integers and qualifier can contain any character *except* the following: \:<>\|?*/ If a version argument is provided, but does not follow the above format, the version will be considered `0.0.0-<user-specified-version-arg>-0` implicitly. See examples below. Argument type: String
path	The path of the original artifact under which one or more files will be added or replaced. The default path is the root. Argument type: String
version	Unique identifier for the artifact version in the form: `major.minor.patch-qualifier-buildNumber` `major, minor, patch`, and `buildNumber` are integers and qualifier can contain any character *except* the following: \:<>\|?*/. If a version argument is provided, but does not follow the above format, the version will be considered `0.0.0-<user-specified-version-arg>-0` implicitly. See examples below. Argument type: String

artifactKey

User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.

Argument type: String

artifactName

The name of the artifact.

Argument type: String

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

excludePatterns

Semi-colon delimited list of file-path patterns indicating which files/directories under "fromDirectory" to exclude when publishing an artifact version. Defaults to "empty," which means no files are excluded. See more information on "pattern syntax" below.

Argument type: Collection

followSymlinks

The default is 1 or true. If 1 or true, CloudBees CD/RO follows symbolic links and record the target file contents with the symbolic link name in the artifact. If 0 or false, CloudBees CD/RO records the symbolic link as a symbolic link. Following symbolic links causes the publish API to remain compatible with previous releases.

Argument type: Boolean

fromDirectory

The directory containing files to publish as the artifact version. A subset of files can be published based on includePatterns and excludePatterns.

Argument type: String

groupId

A user-generated group name for this artifact. This field is limited to alphanumeric characters, spaces, spaces, underscores, hyphens, and periods.

Argument type: String

includePatterns

Semi-colon delimited list of file-path patterns indicating which files/directories under "fromDirectory" to publish in the artifact version. Defaults to "empty," which means all files will be included. Conversely, if only two files are "included," no other files except those two will be included. See more information on "pattern syntax" below.

Argument type: Collection

newVersion

Unique identifier for the new artifact version in the form: major.minor.patch-qualifier-buildNumber major, minor, patch, and buildNumber are integers and qualifier can contain any character except the following: \:<>|?*/ If a version argument is provided, but does not follow the above format, the version will be considered 0.0.0-<user-specified-version-arg>-0 implicitly. See examples below.

Argument type: String

path

The path of the original artifact under which one or more files will be added or replaced. The default path is the root.

Argument type: String

version

Unique identifier for the artifact version in the form: major.minor.patch-qualifier-buildNumber major, minor, patch, and buildNumber are integers and qualifier can contain any character except the following: \:<>|?*/. If a version argument is provided, but does not follow the above format, the version will be considered 0.0.0-<user-specified-version-arg>-0 implicitly. See examples below.

Argument type: String

Positional arguments

None

Response

Publishes a new artifact version to an artifact repository.

ec-perl

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

Examples

# Update the current myGroup:myKey artifact version to version 1.0.0-55.
$cmdr->updateArtifactVersion({artifactName => "myGroup:myKey",
                             newVersion => "1.0.0-55"});▼

ectool

syntax: ectool updateArtifactVersion [optionals]

Example

ectool updateArtifactVersion --artifactName "myGroup:myKey" --newVersion "1.0.0-55"▼

Back to top