Groovy API reference

Artifact

12 minute readReference

addDependentsToArtifactVersion

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

Arguments

Argument Name Type Description

artifactVersionName

String

(Required) The name of the artifactVersion.

dependentArtifactVersions

Collection

List of dependent artifactVersions to add/remove from the artifactVersion.

Positional arguments

artifactVersionName

Usage

ec-perl

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

ectool

ectool addDependentsToArtifactVersion artifactVersionName [optionals]

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.

Arguments

Argument Name Type Description

cacheDirectory

String

(Required) The directory where stale artifact versions are stored

force

Boolean

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

Positional arguments

cacheDirectory

Usage

ec-perl

$cmdr->cleanupArtifactCache(<cacheDirectory>, {<optionals>});

ectool

ectool cleanupArtifactCache cacheDirectory [optionals]

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.

Arguments

Argument Name Type Description

backingStoreDirectory

String

(Required) The repository directory where artifact versions are stored.

force

Boolean

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

If set to "true", this option can be used, so you can clean up 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.

Positional arguments

backingStoreDirectory

Usage

ec-perl

$cmdr->cleanupRepository(<backingStoreDirectory>, {<optionals>});

ectool

ectool cleanupRepository backingStoreDirectory [optionals]

createArtifact

Creates a new artifact.

Arguments

Argument Name Type Description

groupId

String

(Required) The groupId component of the GAV (GroupId/ArtifactKey/Version) coordinates.

artifactKey

String

(Required) The artifactKey component of the GAV (GroupId/ArtifactKey/Version) coordinates.

artifactVersionNameTemplate

String

The artifactVersion name template.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

Positional arguments

groupId, artifactKey

Usage

ec-perl

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

ectool

ectool createArtifact groupId artifactKey [optionals]

createArtifactVersion

Creates a new artifact version.

Arguments

Argument Name Type Description

version

String

(Required) The version component of the GAV (GroupId/ArtifactVersionId/Version) coordinates.

artifactKey

String

The artifactKey component of the GAV (GroupId/ArtifactVersionId/Version) coordinates.

artifactName

String

The name of the artifact containing the artifactVersion.

dependentArtifactVersions

Collection

The set of artifactVersions on which this artifactVersion depends.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

groupId

String

The groupId component of the GAV (GroupId/ArtifactVersionId/Version) coordinates.

jobStepId

UUID

The ID of the job step; used to make a project association.

repositoryName

String

The name of the artifact repository.

Positional arguments

version

Usage

ec-perl

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

ectool

ectool createArtifactVersion version [optionals]

createRepository

Creates a repository for one or more artifacts.

Arguments

Argument Name Type Description

repositoryName

String

(Required) The repository name.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

repositoryDisabled

Boolean

Whether or not to disable the repository.

url

String

The URL for contacting the repository.

zoneName

String

The zone name.

Positional arguments

repositoryName

Usage

ec-perl

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

ectool

ectool createRepository repositoryName [optionals]

deleteArtifact

Deletes an existing artifact element and all artifact versions.

Arguments

Argument Name Type Description

artifactName

String

(Required) The name of the artifact, compose of the group and artifact concatenated by ':', e.g. "group:artifact". Alternatively, the groupId and artifactKey arguments may be used.

artifactKey

String

The artifactKey component of the GAV (GroupId/ArtifactKey/Version) coordinates.

groupId

String

The groupId component of the GAV (GroupId/ArtifactKey/Version) coordinates.

Positional arguments

artifactName

Usage

ec-perl

$cmdr->deleteArtifact(<artifactName>, {<optionals>});

ectool

ectool deleteArtifact artifactName [optionals]

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

Arguments

Argument Name Type Description

artifactVersionName

String

(Required) The name of the artifactVersion.

Positional arguments

artifactVersionName

Usage

ec-perl

$cmdr->deleteArtifactVersion(<artifactVersionName>);

ectool

ectool deleteArtifactVersion artifactVersionName

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

Arguments

Argument Name Type Description

repositoryName

String

(Required) The repository name.

Positional arguments

repositoryName

Usage

ec-perl

$cmdr->deleteRepository(<repositoryName>);

ectool

ectool deleteRepository repositoryName

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.

Arguments

Argument Name Type Description

artifactKey

String

The artifactKey component of the GAV (GroupId/ArtifactVersionId/Version) coordinates.

artifactName

String

The name of the artifact containing the artifactVersion.

artifactVersionName

String

The name of the artifactVersion to find.

filters

Collection

A list of zero or more filter criteria definitions used to define objects to find.

groupId

String

The groupId component of the GAV (GroupId/ArtifactVersionId/Version) coordinates. Defaults to the name of the project that owns the requesting job-step, if there is one. Otherwise, this is a required argument.

includeDependents

Boolean

Whether to include dependent artifact versions in results.

jobStepId

UUID

If the retriever is a job-step, it gets registered as a consumer of the result artifactVersion.

versionRange

String

Optional version range, specified in interval notation.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool findArtifactVersions [optionals]

getArtifact

Retrieves an artifact by name.

Arguments

Argument Name Type Description

artifactName

String

(Required) The name of the artifact, compose of the group and artifact concatenated by ':', e.g. "group:artifact". Alternatively, the groupId and artifactKey arguments may be used.

artifactKey

String

The artifactKey component of the GAV (GroupId/ArtifactKey/Version) coordinates.

groupId

String

The groupId component of the GAV (GroupId/ArtifactKey/Version) coordinates.

Positional arguments

artifactName

Usage

ec-perl

$cmdr->getArtifact(<artifactName>, {<optionals>});

ectool

ectool getArtifact artifactName [optionals]

getArtifacts

Retrieves all artifacts in the system.

Arguments

None.

Positional arguments

None.

Usage

ec-perl

$cmdr->getArtifacts();

ectool

ectool getArtifacts

getArtifactVersion

Retrieves an artifact version by its name.

Arguments

Argument Name Type Description

artifactVersionName

String

(Required) The name of the artifactVersion.

includeRetrieverJobSteps

Boolean

Whether to include retriever job-step information in the response.

includeRetrieverJobs

Boolean

Whether to include retriever job information in the response.

maxRetrievers

Integer

The maximum number of retriever jobs or jobsteps to return.

Positional arguments

artifactVersionName

Usage

ec-perl

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

ectool

ectool getArtifactVersion artifactVersionName [optionals]

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

Argument Name Type Description

artifactName

String

The name of the artifact to use.

retrieverJobId

String

The ID or name of the job to use.

retrieverJobStepId

UUID

The ID of the job step to use.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool getArtifactVersions [optionals]

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.

Arguments

Argument Name Type Description

artifactVersionName

String

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

Positional arguments

artifactVersionName

Usage

ec-perl

$cmdr->getManifest(<artifactVersionName>);

ectool

ectool getManifest artifactVersionName

getRepositories

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

Arguments

None.

Positional arguments

None.

Usage

ec-perl

$cmdr->getRepositories();

ectool

ectool getRepositories

getRepository

Retrieves an artifact repository by its name.

Arguments

Argument Name Type Description

repositoryName

String

(Required) The repository name.

Positional arguments

repositoryName

Usage

ec-perl

$cmdr->getRepository(<repositoryName>);

ectool

ectool getRepository repositoryName

getRetrievedArtifacts

Retrieves artifacts during a job.

Arguments

Argument Name Type Description

jobId

String

(Required) The primary key of the job, or the name of the job.

componentName

String

The name of the component.

resourceName

String

The name of the resource.

Positional arguments

jobId

Usage

ec-perl

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

ectool

ectool getRetrievedArtifacts jobId [optionals]

modifyArtifact

Modifies an existing artifact.

Arguments

Argument Name Type Description

artifactName

String

(Required) The name of the artifact.

artifactKey

String

The artifactKey component of the GAV (GroupId/ArtifactKey/Version) coordinates.

artifactVersionNameTemplate

String

The artifactVersion name template.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

groupId

String

The groupId component of the GAV (GroupId/ArtifactKey/Version) coordinates.

Positional arguments

artifactName

Usage

ec-perl

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

ectool

ectool modifyArtifact artifactName [optionals]

modifyArtifactVersion

Modifies an existing artifact version.

Arguments

Argument Name Type Description

artifactVersionName

String

(Required) The name of the artifact version.

artifactVersionState

ArtifactVersionState

The state of the artifact version.

dependentArtifactVersions

Collection

The set of artifactVersions on which this artifactVersion depends.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

newName

String

The new name for an existing object that is being renamed.

removeAllDependentArtifactVersions

Boolean

If true then all dependencies will be removed.

repositoryName

String

The name of the artifact repository.

Positional arguments

artifactVersionName

Usage

ec-perl

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

ectool

ectool modifyArtifactVersion artifactVersionName [optionals]

modifyRepository

Modifies an existing artifact repository.

Arguments

Argument Name Type Description

repositoryName

String

(Required) The repository name.

description

String

Comment text describing this object that is not interpreted at all by CloudBees CD/RO.

newName

String

The new name for an existing object that is being renamed.

repositoryDisabled

Boolean

Whether or not to disable the repository.

url

String

The URL for contacting the repository.

zoneName

String

The zone name.

Positional arguments

repositoryName

Usage

ec-perl

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

ectool

ectool modifyRepository repositoryName [optionals]

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.

Arguments

Argument Name Type Description

repositoryName

String

(Required) The repository name.

beforeRepositoryName

String

Used when reordering the artifact repositories: the repository is moved to a position just before this repository. Blank means move the repository to the end of the artifact repository list.

Positional arguments

repositoryName

Usage

ec-perl

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

ectool

ectool moveRepository repositoryName [optionals]

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

Argument Name Type Description

artifactName

String

The name of an artifact.

artifactKey

String

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

compress

Boolean

<Boolean flag— 0|1|true|false > Default is "true". Controls whether 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.

dependentArtifactVersions

Collection

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.

description

String

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

excludePatterns

Collection

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

followSymlinks

Boolean

<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 publishing API to remain compatible with previous releases.

fromDirectory

String

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

groupId

String

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

includePatterns

Collection

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.

repositoryName

String

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

version

String

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.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool publishArtifactVersion [optionals]

removeDependentsFromArtifactVersion

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

Arguments

Argument Name Type Description

artifactVersionName

String

(Required) The name of the artifactVersion.

dependentArtifactVersions

Collection

List of dependent artifactVersions to add/remove from the artifactVersion.

Positional arguments

artifactVersionName

Usage

ec-perl

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

ectool

ectool removeDependentsFromArtifactVersion artifactVersionName [optionals]

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

Argument Name Type Description

artifactKey

String

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

artifactName

String

The name of the artifact.

artifactVersionName

String

The name of the artifact version.

cacheDirectory

String

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

filters

Collection

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.

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

  • equals (1 operand)

  • greaterOrEqual (1 operand)

  • greaterThan (1 operand)

  • in (1 operand)

  • lessOrEqual (1 operand)

  • lessThan (1 operand)

  • like (1 operand)

  • notEqual (1 operand)

  • notLike (1 operand)

  • isNotNull (0 operands)

  • isNull (0 operands)

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)

groupId

String

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

includeDependents

Boolean

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

overwrite

String

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 is created and filled with the artifact’s content. If the directory exists, a new directory is created with a unique name and filled with the artifact’s content.

  • 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 are overwritten.

repositoryNames

String

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.

retryNumber

Integer

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

toDirectory

String

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.

versionRange

String

The range of versions to search.

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

Positional arguments

None.

Usage

ec-perl

$cmdr->retrieveArtifactVersions({<optionals>});

ectool

ectool retrieveArtifactVersions [optionals]

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

Argument Name Type Description

artifactKey

String

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

artifactName

String

The name of the artifact.

description

String

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

excludePatterns

Collection

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

followSymlinks

Boolean

<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 publishing API to remain compatible with previous releases.

fromDirectory

String

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

groupId

String

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

includePatterns

Collection

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.

newVersion

String

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.

path

String

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

version

String

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.

Positional arguments

None.

Usage

ec-perl

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

ectool

ectool updateArtifactVersion [optionals]