Using Artifactory 5.x ?
JFrog Artifactory 5.x User Guide


Have a question? Want to report an issue? Contact JFrog support

Skip to end of metadata
Go to start of metadata

Overview

File Specs can be used to specify the details of files you want to upload or download to or from Artifactory. They are specified in JSON format and are currently supported in JFrog CLI, Jenkins Artifactory Plugin and TeamCity Artifactory Plugin.

Download Spec Schema

The download spec schema offers the option of using AQL or wildcard patterns according to the JSON element you specify:

Page contents

{
  "files": [
    {
      "pattern" or "aql": "[Mandatory]",
      "target": "[Mandatory]",
      "props": "[Optional]",
      "recursive": "[Optional, Default: true]",
      "flat": "[Optional, Default: false]",
      "build": "[Optional]"
    }
  ]
}

Where:

Element

Description

pattern

[Mandatory if 'aql' is not specified]
Specifies the source path in Artifactory, from which the artifacts should be downloaded, in the following format: [repository name]/[repository path]. You can use wildcards to specify multiple artifacts.

target

[Mandatory]
Specifies the local file system path to which artifacts which should be downloaded. 

For flexibility in specifying the target path, you can include placeholders in the form of {1}, {2}, {3}...which are replaced by corresponding tokens in the pattern property that are enclosed in parenthesis. For more details, please refer to Using Placeholders.

Since version 2.9.0 of the Jenkins Artifactory plugin and version 2.3.1 of the TeamCity Artifactory plugin the target format has been simplified and uses the same file separator "/" for all operating systems, including Windows.

aql

[Mandatory if 'pattern' is not specified]
An AQL query that specified the artifacts to be downloaded.

props

[Optional]
List of "key=value" pairs separated by a semi-colon. (For example, "key1=value1;key2=value2;key3=value3). Only artifacts with all of the specified properties and values will be downloaded.

flat

[Default: false]
If true, artifacts are downloaded to the exact target path specified and their hierarchy in the source repository is ignored.
If false, artifacts are uploaded to the target path in the file system while maintaining their hierarchy in the source repository.

recursive

[Default: true]
If true, artifacts are also downloaded from sub-paths under the specified path in the source repository.
If false, only artifacts in the specified source path directory are downloaded.

build

[Optional]
If specified, only artifacts of the specified build are downloaded. The "pattern" property is still taken into account when "build" is specified.

The property format is build-name/build-number.

If the build number is not specified, or the keyword LATEST is used for the build number, then the latest published build number is used.

 

Upload Spec Schema

{
  "files": [
    {
      "pattern": "[Mandatory]",
      "target": "[Mandatory]",
      "props": "[Optional]",
      "recursive": "[Optional, Default: 'true']",
      "flat" : "[Optional, Default: 'true']",
      "regexp": "[Optional, Default: 'false']"
    }
  ]
}

Where:

Element

Description

pattern

[Mandatory]

Specifies the local file system path to artifacts which should be uploaded to Artifactory. You can specify multiple artifacts by using wildcards or a regular expression as designated by the regexp property.
If you use a regexp, you need to escape any reserved characters (such as ".", "?", etc.) used in the expression using a backslash "\".

Since version 2.9.0 of the Jenkins Artifactory plugin and version 2.3.1 of the TeamCity Artifactory plugin the pattern format has been simplified and uses the same file separator "/" for all operating systems, including Windows. 

target

[Mandatory]

Specifies the target path in Artifactory in the following format: [repository_name]/[repository_path]

If the pattern ends with a slash, for example "repo-name/a/b/", then "b" is assumed to be a folder in Artifactory and the files are uploaded into it. In the case of "repo-name/a/b", the uploaded file is renamed to "b" in Artifactory.

For flexibility in specifying the upload path, you can include placeholders in the form of {1}, {2}, {3}...which are replaced by corresponding tokens in the source path that are enclosed in parenthesis, For more details, please refer to Using Placeholders.

props

[Optional] 
List of "key=value" pairs separated by a semi-colon ( ; ) to be attached as properties to the uploaded properties. If any key can take several values, then each value is separated by a comma ( , ). For example, "key1=value1;key2=value21,value22;key3=value3".

flat

[Default: true]
If true, artifacts are uploaded to the exact target path specified and their hierarchy in the source file system is ignored.
If false, artifacts are uploaded to the target path while maintaining their file system hierarchy.

recursive

[Default: true]
If true, artifacts are also collected from sub-directories of the source directory for upload.
If false, only artifacts specifically in the source directory are uploaded.

regexp
[Default: false]
If true, the command will interpret the pattern property, which describes the local file-system path of artifacts to upload, as a regular expression.
If false, the command will interpret the pattern property as a wild-card expression.

Using Placeholders

File Specs offer enormous flexibility in how you upload, or download files through use of wildcard or regular expressions with placeholders.

Any wildcard enclosed in parenthesis in the pattern property can be matched with a corresponding placeholder in the target property to determine the name of the artifact once downloaded or uploaded. The following example downloads all zip files, located under the root path of the my-local-repo repository, which include a dash in their name. The files are renamed when they are downloaded, replacing the dash with two dashes.

{
    "files": [
        {
            "pattern": "my-local-repo/(*)-(*).zip",
            "target": "froggy/{1}--{2}.zip",
			"recursive": "false"
        }
    ]
}

 

Examples

Example 1: Download all files located under the all-my-frogs directory in the my-local-repo repository to the froggy/all-my-frogs directory.

{
    "files": [
        {
            "pattern": "my-local-repo/all-my-frogs/",
            "target": "froggy/"
        }
    ]
}

 

Example 2: Download all files retrieved by the AQL query to the froggy directory.

{
  "files": [
    {
      "aql": {
        "items.find": {
          "repo": "my-local-repo",
          "$or": [
            {
              "$and": [
                {
                  "path": {
                    "$match": "."
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            },
            {
              "$and": [
                {
                  "path": {
                    "$match": "*"
                  },
                  "name": {
                    "$match": "a1.in"
                  }
                }
              ]
            }
          ]
        }
      },
      "target": "cli-reg-test/spec-copy-test/aql-a1/"
    }
  ]
}


Example 3: Upload

  1. All zip files located under the resources directory to the zip folder, under the all-my-frogs repository.
    AND 
  2. All TGZ files located under the resources directory to the tgz folder, under the all-my-frogs repository.
  3. Tag all zip files with type = zip and status = ready.
  4. Tag all tgz files with type = tgz and status = ready.
{
  "files": [
    {
      "pattern": "resources/*.zip",
      "target": "my-repo/zip/",
      "props": "type=zip;status=ready"
    },
    {
      "pattern": "resources/*.tgz",
      "target": "my-repo/tgz/",
	  "props": "type=tgz;status=ready"
    }
  ]
]

  • No labels