Update Smart Archiving Policy API

JFrog REST APIs

Content Type
REST API
ft:sourceType
Paligo

Description: This REST API is called to update configuration settings for an existing smart archiving policy.

Note

A policy cannot be updated if it is currently running. If you want to update a policy that is running, you need to either wait for the policy to complete, or manually stop the run by calling Stop Running Smart Archiving Policy API.

Security: Requires a platform admin. A project admin with permission can call this API on the project level.

Usage: PUT http://{host:port}/artifactory/api/archive/v2/packages/policies/{policyKey}

Produces: application/json

Sample Query:

PUT http://{host:port}/artifactory/api/archive/v2/packages/policies/key1
{
   "key": "key1",                          // required
   "description": "updated description",
   "cronExp": "0 15 10 * * ? 2024",
   "durationInMinutes": 150,
   "enabled": false,                       // change only with enable/disable API
   "skipTrashcan": false,
   "searchCriteria": {                     // required
       "packageTypes": [                   // required
           "docker",
           "maven"
       ],
       "repos": [                          // required
           "repo1",
           "repo2"
       ],
       "excludedRepos": [],
       "includedPackages": [               // required
           "com/jfrog"
       ],
       "excludedPackages": [
           "com/jfrog/latest"
       ],
       "includeAllProjects": false,
       "includedProjects": [], 
       "createdBeforeInMonths": 12,
       "lastDownloadedBeforeInMonths": 1,
       "keepLastNVersions": 0
   }
}

Query Parameters:

Field

Type

Description

key

string

The ID that identifies the policy. This ID was configured when creating the policy. You can find the policy ID by calling Get All Smart Archiving Policies API, searching the results for the appropriate description and then its corresponding ID.

description

string

Description that was defined for the policy.

cronExp

integer

The cron expression determines when the policy is run.

durationInMinutes

integer

The maximum duration (in minutes) for policy execution, after which the policy will stop running even if not completed. While setting a maximum run duration for a policy is useful for adhering to a strict archive schedule, it can cause the policy to stop before completion.

enabled

string

A true value means the policy can be executed. A false value means that it cannot.

Note

This API should not be used to enable or disable a policy. To enable or disable a policy, call Enable/Disable Smart Archiving Policy API.

skipTrashcan

string

A true value means that when this policy is executed, packages will be permanently deleted. false means that when the policy is executed packages will be deleted to the Trash Can.

searchCriteria

See below

The criteria that define aspects of the policy such as package types (docker, maven), names of repositories in which the policy will run, and other relevant criteria. For more details see the table below.

Search Criteria:

Field

Type

Description

packageTypes

string

The package types that are archived by the policy. For a list of the permitted package types, click here.Smart Archiving Supported Packages

You must enter at least one package type.

repos

string

Specify one or more patterns for the repository name(s) on which you want the archive policy to run. You can also specify explicit repository names. Specifying at least one pattern or explicit name is mandatory. Only packages in repositories that match the pattern or explicit name will be archived.

excludedRepos

string

Specify patterns for repository names or explicit repository names that you want to be excluded from the archive policy. This parameter is optional.

includedPackages

string

Specify a pattern for a package name or an explicit package name on which you want the archive policy to run. Only one pattern or explicit name can be entered. To include all packages, use "**". For example: "includedPackages": ["**"]

This parameter is mandatory.

excludedPackages

string

Specify explicit package names that you want to be excluded from the policy. Only explicit names (and not patterns) are accepted. This parameter is optional.

includeAllProjects

boolean

Set this value to true if you want the policy to run on all Artifactory projects. The default value is false. This parameter is optional.

Note

This parameter is relevant only on the global level, for Platform Admins.

includedProjects

string

Enter the project keys for the projects on which you want the policy to run. To include repositories that are not assigned to any project, enter the project key default.

Note

This parameter is relevant only on the global level, for Platform Admins.

createdBeforeInMonths

integer

The archive policy will archive packages based on how long ago they were created. For example, if this parameter is 2 then packages created more than 2 months ago will be archived as part of the policy.

Note

  • A policy must use one of the three settings: createdBeforeInMonths, lastDownloadedBeforeInMonths, or keepLastNVersions.

  • createdBeforeInMonths, and lastDownloadedBeforeInMonths can be used together, but they cannot be used with keepLastNVersions. Meaning, use either createdBeforeInMonths and lastDownloadedBeforeInMonths (or just one of them), or use keepLastNVersions.

lastDownloadedBeforeInMonths

integer

The archive policy will archive packages based on how long ago they were downloaded. For example, if this parameter is 5 then packages downloaded more than 5 months ago will be archived as part of the policy.

Note

JFrog recommends using lastDownloadedBeforeInMonths to ensure that packages currently in use are not archived.

keepLastNVersions

integer

Set a value for the number of latest versions to keep. The archive policy will remove all versions before the number you select here. The latest version is always excluded.

Note

  • Versions are determined by creation date.

  • Not all package types support this condition. If you include a package type in your policy that is not compatible with this condition, a validation error (400) is returned. For information on which package types support this condition, click here.Smart Archiving Supported Packages

Sample Response:

{
   "key": "key1",
   "description": "updated description",
   "cronExp": "0 15 10 * * ? 2024",
   "durationInMinutes": 150,
   "enabled": false,
   "skipTrashcan": false,
   "searchCriteria": {
       "packageTypes": [
           "docker",
           "maven"
       ],
       "repos": [
           "repo1",
           "repo2"
       ],
       "excludedRepos": [],
       "includedPackages": [
            "com/jfrog",
       ],
       "excludedPackages": [
            "com/jfrog/latest",
       ],           
       "includeAllProjects": false,
       "includedProjects": [
            "project1",
            "project2"
       ],
       "createdBeforeInMonths": 12,
       "lastDownloadedBeforeInMonths": 1,
       "keepLastNVersions": 0
   }
}

Response Error Codes

Code

Description

400

Validation errors.

401

Bad Credentials.

403

Unauthorized.

404

A policy with the specified key does not exist.

500

Internal server error.