Create an Archive Policy

JFrog REST APIs

Products
JFrog Xray
Content Type
REST API
ft:sourceType
Paligo

Description: Creates a new archive policy in Artifactory using the provided policy configuration.

Note

This Cold Storage feature is available only for Artifactory Enterprise and Enterprise+ users.

Since: Artifactory 7.27.3

Security: Requires an admin user

Usage: POST /api/retention/archive/policies/{key}

Produces: application/json

Consumes: application/json

Request Parameters:

Parameters

Type

Description

Required/Optional

packageRetention

boolean

Determines whether the archive policy works on packages (true) or artifacts (false).

The default value is false.

Required

key

string

Unique policy key that identifies the policy.

Required

enabled

boolean

Enable/disable policy. If disabled, policy execution is blocked.

Required

cronExp

string

The Cron expression for scheduling the policy.

Required

aqlQuery

string

Search for artifacts to be archived using Artifactory Query Language (AQL). This can be used instead of searchCriteriaForm to include/exclude artifacts in the retention policy.

The AQL query can be to:

  • Include or exclude a repository, inner path, or artifact name (one or many)

  • Include or exclude associated properties (one or many)

  • Include an age

  • Last downloaded before configurable X (weeks, months, years)

  • Deployed before configurable X (weeks, months, years)

Note

You may run AQL queries only on the Item domain. Other primary domains, such as Build, Entry, Promotion, and Release are not supported.

Required if searchCriteriaForm is not provided.

Note

aqlquery cannot be used for packages.

searchCriteriaForm

string

Search Criteria Form for retention policy. This can be used instead of aqlQuery to include/exclude artifacts in the retention policy.

Required if aqlQuery is not provided

description

string

Description for the policy.

Optional

durationInMinutes

long

The maximum duration (in minutes) for policy execution. If policy execution exceeds this period, it is stopped.

Optional

expirationTimeInMonths

long

The expiration period (in months) that it takes for archived artifacts to be cleaned up from the Cold instance.

Optional

skipTrashcan

boolean

Prevent the transfer of the artifacts to the trash can repository, and allow the artifacts to be deleted by a full GC cleanup.Browsing ArtifactsManaging Disk Space Usage

Default value is false.

Optional

Package Search Criteria Form

Field

Type

Description

Required/Optional

packageType

string

The package type to be archived (for example, Docker).

Required

componentName

string

Wildcards are supported.

Optional

version

string

Wildcards are supported.

Optional

packageRepos

string

List of repository keys included in the package to be archived.

Required

createdBefore

long

Include all items that were created before the time provided (in ms).

Optional

downloadedBefore

long

Include all items that were last downloaded before the time provided (in ms).

Optional

Artifact Search Criteria Form

You must define at least one of the following criteria in your search:

  • Properties

  • Path

  • Names

  • Repositories

Field

Type

Description

properties

string

Include/Exclude all properties with the specified propertyKey and a single propertyValue.

Supports and/or operator.

Example

    "properties": {
      "include": {
        "operator": "or",
        "values": [
          {
            "propertyKey": "example-prop-key-1",
            "propertyValue": "prop-val-1"
          },
          {
            "propertyKey": "example-prop-key-1",
            "propertyValue": "prop-val-2"
          }
        ]
      },
      "exclude": {
        "operator": "or",
        "values": [
          {
            "propertyKey": "example-prop-key-2",
            "propertyValue": "prop-val-1"
          }
        ]
      }
    }

repositories

string

Include/Exclude all repository keys.

Supports and/or operator.

ExampleExample

    "repositories": {
      "include": {
        "operator": "or",
        "values": [
          "repo-1",
          "repo-2"
        ]
      },
      "exclude": {
        "operator": "and",
        "values": [
          "repo-*",
          "*-3"
        ]
      }
    }

path

string

Include/Exclude all items with specified paths

Supports and/or operator.

ExampleExample

    "paths": {
      "include": {
        "operator": "or",
        "values": [
          "path-1",
          "path-2"
        ]
      },
      "exclude": {
        "operator": "or",
        "values": [
          "path-3"
        ]
      }
    }

name

string

Include/Exclude all items with the specified names.

Supports and/or operator.

ExampleExample

    "names": {
      "include": {
        "operator": "or",
        "values": [
          "name-1",
          "name-2"
        ]
      },
      "exclude": {
        "operator": "or",
        "values": [
          "name-3"
        ]
      }
    }

createdBefore

long

Include all items that were created before the time provided (in months).

downloadedBefore

long

Include all items that were last downloaded before the time provided (in months).

Sample Artifact Request: Using aqlQuery parameter

POST /api/retention/archive/policies/example-policy-key

{
   "key": "example-policy-key",
   "enabled": true,
   "description": "policy description",
   "aqlQuery": "items.find({\"type\":{\"$eq\":\"file\"}})",
   "cronExp": "0 15 10 L * ?",
   "durationInMinutes": 0,
   "expirationTimeInMonths": 0,
   "skipTrashcan": true
}

Sample Response: Same as request.

Sample Artifact Request: Using searchCriteriaForm parameter

POST /api/retention/archive/policies/example-policy-key

{
  "key": "myPolicy",
  "description": "Demo policy - archive using search criteria form",
  "enabled": true,
  "searchCriteriaForm": {
    "properties": {
      "include": {
        "values": [{
            "propertyKey":"sd",
            "propertyValue":"sd"
        }]
      },
      "exclude": {
        "values": [
        ]
      }
    },
    "repositories": {
      "include": {
        "values": [
          "include-*",
          "*-repo"
        ]
      },
      "exclude": {
        "values": []
      }
    },
    "paths": {
      "include": {
        "values": []
      },
      "exclude": {
        "values": [
          "exclude-*",
          "*-path"
        ]
      }
    },
    "createdBefore":2,
    "downloadedBefore":3
}
}

Sample Response: Same as request.

Sample Package Request:

{
    "key": "package-local-to-local-policy-6095",
    "enabled": true,
    "skipTrashcan": true,
    "packageRetention": true,
    "packageSearchCriteriaForm": {
        "packageType": "docker",
        "packageRepos": [
            "package-archive-local-to-local-repo-6095"
        ]
    }
}

Sample Response: Same as request.

Status:

201: Success

409: If a policy with the specified policyKey already exists, the call fails with a 409 response.