Artifact Management Commands

22 minute readReference

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

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,]"

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

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"

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

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"

createArtifact

Creates a new artifact.

You must specify groupId and artifactKey.

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

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"

createArtifactVersion

Creates a new artifact version.

You must specify version.

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

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

createRepository

Creates a repository for one or more artifacts.

You must specify a repositoryName.

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

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"

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

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"

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

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"

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

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"

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

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.

getArtifact

Retrieves an artifact by name.

You must specify an artifactName.

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"

getArtifacts

Retrieves all artifacts in the system.

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

getArtifactVersion

Retrieves an artifact version by its name.

You must specify an artifactVersionName.

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

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"

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

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"

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

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

getRepositories

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

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

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

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"

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

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"

modifyArtifact

Modifies an existing artifact.

You must specify an artifactName.

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

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"

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

modifyRepository

Modifies an existing artifact repository.

You must specify a repositoryName.

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

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"

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

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"

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

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

===Version number examples

User Input Interpretation

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"

removeDependentsFromArtifactVersion

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

You must specify the artifactVersionName.

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

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"

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

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"

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

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

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.

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

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

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"