Index
addResourcePoolToEnvironmentTieraddResourceTemplateToEnvironmentTemplateTieraddResourceToEnvironmentTemplateTiercreateEnvironmentTemplatecreateEnvironmentTemplateTiercreateEnvironmentTemplateTierMapcreateHookcreateResourceTemplatedeleteEnvironmentTemplatedeleteEnvironmentTemplateTierdeleteEnvironmentTemplateTierMapdeleteEnvironmentTemplateTierMappingdeleteHookdeleteResourceTemplategetAvailableResourcesForEnvironmentgetEnvironmentTemplategetEnvironmentTemplatesgetEnvironmentTemplateTiergetEnvironmentTemplateTierMapsgetEnvironmentTemplateTiersgetHookgetHooksgetProvisionedEnvironmentsgetResourcePoolsInEnvironmentTiergetResourcesInEnvironmentTemplateTiergetResourceTemplategetResourceTemplatesgetResourceTemplatesInEnvironmentTemplateTiermodifyEnvironmentTemplatemodifyEnvironmentTemplateTiermodifyEnvironmentTemplateTierMapmodifyEnvTemplTierResourceTemplMappingmodifyHookmodifyResourceTemplateprovisionEnvironmentprovisionResourcePoolremoveResourceFromEnvironmentTemplateTierremoveResourcePoolFromEnvironmentTierremoveResourceTemplateFromEnvironmentTemplateTier
getPluginCatalog
getServerSettingsCategories
processWebhookTrigger
getWorkItems

retrieveArtifactVersions

Back to index

Summary

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.

artifactKey
Stringoptional
User-specified identifier for this artifact. This field is limited to alphanumeric characters, spaces, underscores, hyphens, and periods.
artifactName
Stringoptional
The name of the artifact.
artifactVersionName
Stringoptional
The name of the artifact version.
cacheDirectory
Stringoptional
The directory where the artifact version is stored. The artifact version files are stored in a subdirectory under this cache directory.
filters
Arrayoptional

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
Stringoptional
A user-generated group name for this artifact. This field may consist of alphanumeric characters, spaces, underscores, hyphens, and periods.
includeDependents
Booleanoptional

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
Stringoptional

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
Stringoptional

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
Integeroptional
Number of retry attempts for the operation. The default is 1. The time between retry attempts is 20 seconds.
toDirectory
Stringoptional

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
Stringoptional

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

Usage

Perl

$cmdr->retrieveArtifactVersions(
  # optionals
);
▼

ectool

ectool retrieveArtifactVersions \
  # optionals
▼

Examples

Perl

# 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

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 call in the Perl API.