Retrieve Artifact Version Step

3 minute readAutomation

The following parameters are available to create this step:

Field Name Description


Artifact name, in the form <groupId>:<artifactKey>.


Select the latest version ( Latest ), the exact version of the artifact ( Exact ), or a version range ( Range ). Version is in the form: <major>.<minor>.<patch>-<qualifier>-<buildNumber>

Retrieve to directory

If you want to retrieve this artifact version to a specific directory location, select the check box, then specify the full path to the directory where you want to retrieve this artifact version.


Use the drop-down menu to select one of the following options:

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

Retrieved Artifact Location Property

Name or property sheet path used by the step to create a property sheet. This property sheet stores information about the retrieved artifact versions as XML in the artifactVersionXML child property, and the file system location of the retrieved artifact version in the cacheLocation child property. The initial value of this field includes $[assignedResourceName] as one of the levels in the property path because different resources may have different cache directories, and you do not want a retrieval on one resource to clobber the data regarding a retrieval on a different resource. Typically, a step that needs to use files from an artifact retrieved by this step will specify it in a Perl script similar to this:

my $cmdr = new ElectricCommander();` `my $xpath = $cmdr->getProperty("/myJob/retrieveArtifactVersions/$[assignedResourceName] /MyGrp:MyKey/cacheLocation"); my $retrieveDir = $xpath->findvalue("//value")->value(); system("java", "-cp", "$retrieveDir/lib/bar.jar", "Bar");

This example shows how to retrieve the location of the retrieved MyGrp:MyKey artifact version on the resource, and add a file ( bar.jar ) in its lib directory to classpath, so the Bar class can be run.


Enter search filters, one per line, applicable to querying the CloudBees CD/RO database for the artifact version to retrieve.

Artifact Retrieval Dependency Order Explained

The order of dependencies registered for an artifact version are significant.

Consider this scenario:

  • A depends on B (any version) and C [1.0, 2.0)

  • B depends on C (any version)

  • C versions 1.0, 2.0, and 3.0 exist

When retrieving A, the dependency algorithm evaluates B first. The algorithm finds that the max version of B depends on any version of C, so the algorithm looks for max version C and finds C 3.0. Because this chain is satisfied, the algorithm returns to A and evaluates its next dependency "C [1.0, 2.0)". This results in matching C 1.0.

The returned artifacts are: A, B, C 1.0, and C 3.0.

Consider if the A dependency is changed to:

  • A depends on C [1.0, 2.0), B (any version)

The algorithm will choose C 1.0 first. Then the algorithm evaluates B, determines that its "C (any version)" is satisfiable by the already-chosen C 1.0.

The returned artifacts are A, B, and C 1.0.

In the version range syntax [] indicates inclusive, and () indicates exclusive.