You are here: ectool and the Commander API > API Commands - listed by group and in alphabetical order > Artifact Management

API commands - Artifact Management


addDependentsToArtifactVersion
cleanupArtifactCache
cleanupRepository
createArtifact
createArtifactVersion
createRepository
deleteArtifact
deleteArtifactVersion
deleteRepository
findArtifactVersions
getArtifact
getArtifacts
getArtifactVersion

getArtifactVersions
getManifest
getRepositories
getRepository
modifyArtifact
modifyArtifactVersion
modifyRepository
moveRepository
publishArtifactVersion
removeDependentsFromArtifactVersion
resolveRoute
retrieveArtifactVersions

API commands - Artifact Management

removeDependentsFromArtifactVersion

resolveRoute

API commands - Artifact Management

 

 

 

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 Commander server  interprets the name form correctly.

Argument type: String

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

Positional arguments

artifactVersionName

Response

None or status OK message.

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

Example
ectool addDependentsToArtifactVersion --artifactVersionName "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 Commander server.

Note: 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" 

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 Commander server.

Note: 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 backingstore 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
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

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

Argument type: String

artifactVersionNameTemplate

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

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

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
version

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

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

Name of the artifact.

Argument type: String

dependentArtifactVersions

The set of artifact versions on which this artifactVersion depends.

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

groupId

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

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

Argument type: UUID

repositoryName

The name of the artifact repository.

Argument type: String

Positional arguments

version

Response

Returns an artifact element.

ec-perl

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

Example
$cmdr->createArtifactVersion("thirdPartyTools", "SDK", {description => "3rd party tools SDK"}); 
ectool

syntax: ectool createArtifactVersion <groupId> <artifactKey> ...

Example
ectool createArtifactVersion thirdPartyTools SDK --description "3rd party tools SDK" 

Back to Top

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

repositoryDisabled

<Boolean flag -0|1|true|false>  Determines whether the repository is disabled. Default is "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> ...

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

Positional arguments

artifactName

Response

None or a status OK message.

ec-perl

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

Example
$cmdr->deleteArtifact("commander:SDK"); 
ectool

syntax: ectool deleteArtifact <artifactName>

Example
ectool deleteArtifact "commander:SDK" 

Back to Top

deleteArtifactVersion

Deletes artifact version metadata from the Commander 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.

Note: 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 Commander 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 Commander 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 to delete.

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.

Note: The retrieveArtifactVersions API uses this API to find the appropriate artifact version in the Commander 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.

Argument type: String

artifactName

The name of an artifact.

Argument type: String

artifactVersionName

The name of an artifact version.

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 ElectricCommander Perl API.

Two types of filters:

"property filters" - used to select objects based on the value of the object's intrinsic or custom property

"boolean filters" ("and", "or", "not") - used to combine one or more filters using boolean logic.

Each "property filter" consists of a property name to test and an operator to use for comparison. The property can be either an intrinsic property defined by Commander 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

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

This command 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 dependent(s).

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

Positional arguments

artifactName

Response

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

You must specify search filter criteria to find the artifacts you need.


Arguments Descriptions
None
Positional arguments

None

Response

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
artifactVersionName

The name of the artifact version to retrieve.

Note: 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 ElectricCommander server interprets either name form correctly.

Argument type: String

includeRetrieverJobs

<Boolean flag - 0|1|true|false>  If set to 1, 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

<Boolean flag - 0|1|true|false>  If set to 1, 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

If one of the includeRetriever* options are specified, return at most "this many" of the most recent retrievers. Without this option, the Commander server will return all retrievers.

Argument type: String

Positional arguments

artifactVersionName

Response

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

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 that retrieved an artifact.

Argument type: String

retrieverJobStepId

The job step ID that retrieved an artifact.

Argument type: UUID

Positional arguments

None

Response

Zero or more artifactVersion elements.

ec-perl

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

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

syntax: ectool getArtifactVersions ...

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

Positional arguments

None

Response

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 Commander server.

Arguments Descriptions
None
Positional arguments

None

Response

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

Positional arguments

repositoryName

Response

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

modifyArtifact

Modifies an existing artifact.

You must specify an artifactName.


Arguments Descriptions
artifactName

The name of the artifact to modify.

Argument type: String

artifactVersionNameTemplate

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

Positional arguments

artifactName

Response

None or a status OK message.

ec-perl

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

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

syntax: ectool modifyArtifact <artifactName> ...

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.

Note: 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 ElectricCommander server interprets either name form correctly.

Argument type: String

artifactVersionState

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

Argument type: ArtifactVersionState

dependentArtifactVersions

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

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

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

newName

New name for this artifact version.

Argument type: String

removeAllDependentArtifactVersions

<Boolean flag - 0|1|true|false> Defaults to "false."
Removes all dependent artifacts from this artifact version. Subsequent "retrieves" will no longer retrieve dependent artifacts for this artifact version.

Argument type: Boolean

repositoryName

The name of the artifact repository.

Argument type: String

Positional arguments

artifactVersionName

Response

None or a status OK message.

ec-perl

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

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

syntax: ectool modifyArtifactVersion <artifactVersionName> ...

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
repositoryName

The name of the artifact repository.

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

newName

New name of the repository.

Argument type: String

repositoryDisabled

<Boolean flag - 0|1|true|false> Marks the repository as enabled or disabled. If you do not enter this option, the state of the repository is unchanged.

Argument type: Boolean

url

The URL used to communicate with the artifact repository.

Argument type: String

zoneName

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("myNewRepos", {newName => "cmdrRepository"});
ectool

syntax: ectool modifyRepository <repositoryName> ...

Example
ectool modifyRepository myNewRepos --newName cmdrRepository

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 Commander 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

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

Example
ectool moveRepository reposThree --beforeRepositoryName reposOne

Back to Top

publishArtifactVersion

Publishes an artifact version to an artifact repository.

Note: 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

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

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

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

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
artifactVersionName

The name of the artifact version from which you want to remove dependents.
Note: 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 Commander server interprets either name form correctly.

Argument type: String

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

Positional arguments

artifactVersionName

Response

None or 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> ...

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.


Arguments Descriptions
toRepositoryName

Name of the artifact repository.

Argument type: String

fromAgentId

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

Argument type: Long

fromResourceName

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("WebServer", {fromResourceName => "admin"});
ectool

syntax: ectool resolveRoute <toRepositoryName> [optionals...]

Example
ectool resolveRoute "WebServer" --fromResourceName "admin" 

Back to Top

retrieveArtifactVersions

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

Note: 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.

Note: 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 ElectricCommander 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 Commander 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

Options are:

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

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

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

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

Note: 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

of