Plugin Template Source

/*
 * Copyright (C) 2011 JFrog Ltd.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 *
 * Globally bound variables:
 *
 * log (org.slf4j.Logger)
 * repositories (org.artifactory.repo.Repositories)
 * security (org.artifactory.security.Security)
 * searches (org.artifactory.search.Searches) [since: 2.3.4]
 * builds (org.artifactory.build.Builds) [since 2.5.2]
 *
 * ctx (org.artifactory.spring.InternalArtifactoryContext) - NOT A PUBLIC API - FOR INTERNAL USE ONLY!
 */

upload {
  /**
   * Handle before any upload events, at this point the request passed all of Artifactory's filters (authentication etc) and is about to reach the
   * repositories.
   * 
   * Context variables:
   * modifiedRepoPath (org.artifactory.repo.RepoPath) 
   * Forces Artifactory to store the file at the specified repository path.
   *
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request.
   * repoPath (org.artifactory.repo.RepoPath) -  a read-only parameter of the request RepoPath (containing the
   *                                                    repository the resource should be at).
   */
  beforeUploadRequest { request, repoPath ->
  }

download {
  /**
   * Provide an alternative response, by one of the following methods:
   * (1) Setting a success/error status code value and an optional error message.
   * (2) Provide an alternative download content, by setting new values for the inputStream and size context variables.
   *
   * Note that, unless specifically handled, checksum requests for altered responses will return the checksum of the
   * original resource, which may not match the checksum of the alternate response.
   *
   * Will not be called if the response is already committed (e.g. a previous error occurred).
   * Currently called only for GET requests where the resource was found.
   *
   * Context variables:
   * status (int) - a response status code. Defaults to -1 (unset).
   * message (java.lang.String) - a text message to return in the response body, replacing the response content.
   *                              Defaults to null.
   * inputStream (java.io.InputStream) - a new stream that provides the response content. Defaults to null.
   * size (long) - the size of the new content (helpful for clients processing the response). Defaults to -1.
   * headers (java.util.Map<String,String>) - Map containing the extra headers to override or add if not exists to the response.
   *
   * Usage example:
   * headers = ["ExtraHeader":"SpecialHeader"] 
   *
   *
   *
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request.
   * responseRepoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the response RepoPath (containing the
   *                                                    physical repository the resource was found in).
   */
  altResponse { request, responseRepoPath ->
  }

 /**
  * Provide an alternative response, by one or more of the following methods:
  * (1) Setting a success/error status code value and an optional error message.
  * (2) Provide an alternative download content, by setting new values for the inputStream and size context variables.
  * (3) Setting response headers
  *
  * Note that, unless specifically handled, checksum requests for altered responses will return the checksum of the
  * original resource, which may not match the checksum of the alternate response.
  *
  * Will not be called if the response is already committed (e.g. a previous error occurred).
  * Called for GET and HEAD requests where the resource was found or was not modified.
  *
  * Context variables:
  * status (int) - a response status code. Defaults to the response original status.
  * message (java.lang.String) - a text message to return in the response body, replacing the response content, or as an error message.
  *               Defaults to null.
  * inputStream (java.io.InputStream) - a new stream that provides the response content. Defaults to null.
  * size (long) - the size of the new content (helpful for clients processing the response). Defaults to -1.
  * headers (java.util.Map<String,String>) - Map containing the extra headers to override or add if not exists to the response.
  *
  * Usage example:
  * headers = ["ExtraHeader":"SpecialHeader"]
  *
  *
  *
  * Closure parameters:
  * request (org.artifactory.request.Request) - a read-only parameter of the request.
  * responseRepoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the response RepoPath (containing the
  *                          physical repository the resource was found in).
  */
 altAllResponses { request, responseRepoPath ->
 }

  /**
   * Provides an alternative download path under the same remote repository, by setting a new value to the path
   * variable.
   *
   * Context variables:
   * path (java.lang.String) - the new path value. Defaults to the originalRepoPath's path.
   *
   * Closure parameters:
   * repoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the original request RepoPath.
   */
  altRemotePath { repoPath ->
  }

  /**
   * Provide an alternative download content, by setting new values for the inputStream and size context variables.
   *
   * Context variables:
   * inputStream (java.io.InputStream) - a new stream that provides the response content. Defaults to null.
   * size (long) - the size of the new content (helpful for clients processing the response). Defaults to -1.
   *
   * Closure parameters:
   * repoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the original request RepoPath.
   */
  altRemoteContent { repoPath ->
  }
 
   /**
    * In case of resolution error provide an alternative response, by setting a success/error status code value and an optional error message.
    * Will not be called if the response is already committed (e.g. a previous error occurred).
    * As opposite to altResponse, called only for GET requests during which error occurred (e.g. 404 - not found, or 409 - conflict).
    *
    * Context variables:
    * status (int) - a response error status code (may be overridden in the plugin).
    * message (java.lang.String) - a response error message (may be overridden in the plugin).
    * inputStream (java.io.InputStream) - a new stream that provides the response content. Defaults to null.
    * size (long) - the size of the new content (helpful for clients processing the response). Defaults to -1.
     *
     * Closure parameters:
     * request (org.artifactory.request.Request) - a read-only parameter of the request.
     */
  afterDownloadError { request ->
  }

  /**
   * Handle before remote download events.
   *
   * Context variables:
   * headers (java.util.Map<String,String>) - Map containing the extra headers to insert into the remote server request
   * 
   * Usage example:
   * headers = ["ExtraHeader":"SpecialHeader"]      
   *
   * Note: The following cannot be used as extra headers and Artifactory will always override them: 
   * "X-Artifactory-Originated". "Origin-Artifactory", "Accept-Encoding"
   *
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request. [since: 2.3.4]
   * repoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the original request RepoPath.
   */
  beforeRemoteDownload { request, repoPath ->
  }

  /**
   * Handle after remote download events.
   *
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request. [since: 2.3.4]
   * repoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the original request RepoPath.
   */
  afterRemoteDownload { request, repoPath ->
  }

  /**
   * Handle before local download events.
   *
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request.
   * responseRepoPath (org.artifactory.repo.RepoPath) - a read-only parameter of the response RepoPath (containing the
   *                                                    physical repository the resource was found in).
   */
  beforeDownload { request, responseRepoPath ->
  }
 
  /**
   * Handle before any download events, at this point the request passed all of Artifactory's filters (authentication etc) and is about to reach the repositories.
   * 
   * Context variables:
   * expired (boolean) - Mark the requested resource as expired. Defaults to false (unset).
   *                     An expired resource is one that it's (now() - (last updated time)) time is higher than the repository retrieval cache period milliseconds.
   *                     Setting this option to true should be treated with caution, as it means both another database hit (for updating the last updated time)
   *                                     as well as network overhead since if the resource is expired, a remote download will occur to re-download it to the cache.
   *                                     A common implementation of this extension point is to check if the resource comply with a certain pattern (for example: a *.json file)
   *                                     AND the original request was to the remote repository (and not directly to it's cache) 
   *                                     AND a certain amount of time has passed since the last expiry check (to minimize DB hits).
   *                                     See our public GitHub for an example here: https://github.com/JFrog/artifactory-user-plugins/blob/master/download/beforeDownloadRequest/beforeDownloadRequest.groovy
   *
   * modifiedRepoPath (org.artifactory.repo.RepoPath) 
   *                                     Forces Artifactory to store the file at the specified repository path in the remote cache.
   *                                     See our public GitHub for an example here: https://github.com/JFrog/artifactory-user-plugins/blob/master/download/modifyMD5File/ModifyMD5FileTest.groovy
   * Closure parameters:
   * request (org.artifactory.request.Request) - a read-only parameter of the request.
   * repoPath (org.artifactory.repo.RepoPath) -  a read-only parameter of the response RepoPath (containing the
   *                                                    physical repository the resource was found in).
   */
  beforeDownloadRequest { request, repoPath ->
  }
}

If you want to abort an action, you can do that in 'before' methods by throwing a runtime org.artifactory.exception.CancelException with an error message and a proper http error code.

storage { 
 
 /** 
 * Handle before create events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the original item being created. 
 */ 
 beforeCreate { item -> 
 } 
 
 /** 
 * Handle after create events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the original item being created. 
 */ 
 afterCreate { item -> 
 } 
 
 /** 
 * Handle before delete events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the original item being being deleted. 
 */ 
 beforeDelete { item -> 
 } 
 
 /** 
 * Handle after delete events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the original item deleted. 
 */ 
 afterDelete { item -> 
 } 
 
 /** 
 * Handle before move events. 
 * 
 * Closure parameters: 
 
 * item (org.artifactory.fs.ItemInfo) - the source item being moved. 
 * targetRepoPath (org.artifactory.repo.RepoPath) - the target repoPath for the move. 
 */ 
 beforeMove { item, targetRepoPath, properties -> 
 } 
 
 /** 
 * Handle after move events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the source item moved. 
 * targetRepoPath (org.artifactory.repo.RepoPath) - the target repoPath for the move. 
 */ 
 afterMove { item, targetRepoPath, properties -> 
 } 
 
 /** 
 * Handle before copy events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the source item being copied. 
 * targetRepoPath (org.artifactory.repo.RepoPath) - the target repoPath for the copy. 
 */ 
 beforeCopy { item, targetRepoPath, properties -> 
 } 
 
 /** 
 * Handle after copy events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the source item copied. 
 * targetRepoPath (org.artifactory.repo.RepoPath) - the target repoPath for the copy. 
 */ 
 afterCopy { item, targetRepoPath, properties -> 
 } 
 
 /** 
 * Handle before property create events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the item on which the property is being set. 
 * name (java.lang.String) - the name of the property being set. 
 * values (java.lang.String[]) - A string array of values being assigned to the property. 
 */ 
 beforePropertyCreate { item, name, values -> 
 } 
 /** 
 * Handle after property create events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the item on which the property has been set. 
 * name (java.lang.String) - the name of the property that has been set. 
 * values (java.lang.String[]) - A string array of values assigned to the property. 
 */ 
 afterPropertyCreate { item, name, values -> 
 } 
 /** 
 * Handle before property delete events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the item from which the property is being deleted. 
 * name (java.lang.String) - the name of the property being deleted. 
 */ 
 beforePropertyDelete { item, name -> 
 } 
 /** 
 * Handle after property delete events. 
 * 
 * Closure parameters: 
 * item (org.artifactory.fs.ItemInfo) - the item from which the property has been deleted. 
 * name (java.lang.String) - the name of the property that has been deleted. 
 */ 
 afterPropertyDelete { item, name -> 
 } 
} 

jobs {

  /**
   * A job definition.
   * The first value is a unique name for the job.
   * Job runs are controlled by the provided interval or cron expression, which are mutually exclusive.
   * The actual code to run as part of the job should be part of the job's closure.
   *
   * Parameters:
   * delay (long) - An initial delay in milliseconds before the job starts running (not applicable for a cron job).
   * interval (long) -  An interval in milliseconds between job runs.
   * cron (java.lang.String) - A valid cron expression used to schedule job runs

  myJob(interval: 1000, delay: 100) {
  }

  mySecondJob(cron: "0/1 * * * * ?") {
  }
}

curl -X GET -v -u admin:password "http://localhost:8080/artifactory/api/plugins/execute/myExecution?params=msg=And+the+result+is:|no1=10|no2=15&async=0"

executions {
 
  /**
   * An execution definition.
   * The first value is a unique name for the execution.
   *
   * Context variables:
   * status (int) - a response status code. Defaults to -1 (unset). Not applicable for an async execution.
   * message (java.lang.String) - a text message to return in the response body, replacing the response content.
   *                              Defaults to null. Not applicable for an async execution.
   *
   * Plugin info annotation parameters:
   *  version (java.lang.String) - Closure version. Optional.
   *  description (java.lang.String) - Closure description. Optional.
   *  httpMethod (java.lang.String, values are GET|PUT|DELETE|POST) - HTTP method this closure is going
   *    to be invoked with. Optional (defaults to POST). 
   *  params (java.util.Map<java.lang.String, java.lang.String>) - Closure default parameters. Optional.
   *  users (java.util.Set<java.lang.String>) - Users permitted to query this plugin for information or invoke it. 
   *  groups (java.util.Set<java.lang.String>) - Groups permitted to query this plugin for information or invoke it.
   *
   * Closure parameters:
   *  params (java.util.Map) - An execution takes a read-only key-value map that corresponds to the REST request
   *    parameter 'params'. Each entry in the map contains an array of values. This is the default closure parameter,
   *    and so if not named it will be "it" in groovy.
   *  ResourceStreamHandle body - Enables you to access the full input stream of the request body.
   *    This will be considered only if the type ResourceStreamHandle is declared in the closure.
   */
 
  myExecution(version:version, description:description, httpMethod: 'GET', users:[], groups:[], params:[:]) { params ->
  }

  execWithBody(version:version, description:description, httpMethod: 'GET', users:[], groups:[], params:[:]) { params, ResourceStreamHandle body ->
  }

}

Realms defined here are added before any built-in realms (Artifactory internal realm, LDAP, Crowd etc.). User authentication will be attempted against these realms first, by the order they are defined.

realms {

  /**
   * A security realm definition.
   * The first value is a unique name for the realm.
   *
   * Closure parameters:
   * autoCreateUsers (boolean) - Whether to automatically create users in Artifactory upon successful login. Defaults to
   * true. When false, the user will be transient and their privileges will be managed according to permissions defined for auto-join groups.
   * realmPolicy (org.artifactory.security.RealmPolicy): (Optional) - If included with value RealmPolicy.ADDITIVE, plugin will be executed only if the user has previously been authenticated, and allows enrichment of the authenticated               
   * user with additional data. 
   * See our public GitHub for an example here: https://github.com/JFrog/artifactory-user-plugins/blob/master/security/synchronizeLdapGroups/synchronizeLdapGroups.groovy
   */

  myRealm(autoCreateUsers: true, realmPolicy: RealmPolicy.ADDITIVE) {
    /**
     * Implementation should return true/false as the result of the authentication.
     *
     * Context variables:
     * groups (java.lang.String[]) - An array of groups that the authenticated user should be associated with (since 3.0.2).
         * user (org.artifactory.security.User) - The authenticated user.
     *
     * Closure parameters:
     * username (java.lang.String) - The username
     * credentials (java.lang.String) - The password
     */
    authenticate { username, credentials ->
    }

    /**
     * Implementation should return true if the user is found in the realm.
     * Closure parameters:
     * username (java.lang.String) - The username
     */
    userExists { username ->
    }
  }
}

build {
  
  /**
   * Handle before build info save events
   *
   * Closure parameters:
   * buildRun (org.artifactory.build.DetailedBuildRun) - Build Info model to be saved. Partially mutable. 
   */
  beforeSave { buildRun ->
  }
 
  /**
   * Handle after build info save events
   *
   * Closure parameters:
   * buildRun (org.artifactory.build.DetailedBuildRun) - Build Info that was saved. Partially mutable.
   */
  afterSave { buildRun ->
  }
}

promotions {
 
  /**
   * A REST executable build promotion definition.
   *
   * Context variables:
   * status (int) - a response status code. Defaults to -1 (unset).
   * message (java.lang.String) - a text message to return in the response body, replacing the response content. Defaults to null.
   *
   * Plugin info annotation parameters:
   * version (java.lang.String) - Closure version. Optional.
   * description (java.lang.String - Closure description. Optional.
   * params (java.util.Map<java.lang.String, java.lang.String>) - Closure parameters. Optional.
   * users (java.util.Set<java.lang.String>) - Users permitted to query this plugin for information or invoke it. 
   * groups (java.util.Set<java.lang.String>) - Groups permitted to query this plugin for information or invoke it.
   *
   * Closure parameters:
   * buildName (java.lang.String) - The build name specified in the REST request.
   * buildNumber (java.lang.String) - The build number specified in the REST request.
   * params (java.util.Map<java.lang.String, java.util.List<java.lang.String>>) - The parameters specified in the REST request.
   */
  promotionName(version, description, users, groups, params) { buildName, buildNumber, params ->
  }
}

/**
 * Set of staging strategy definitions to be used by the build server during staging process.
 * The strategy provides the build server with the following information:
 * 1. How the artifacts in the staged build should be versioned;
 * 2. How the artifacts in the next integration build should be versioned;
 * 3. Should the build server create a release branch/tag/stream in VCS and how it should be called;
 * 4. To which repository in Artifactory the built artifacts should be submitted.
 *
 * This user plugin is called by the build server using REST call.
 */
staging {
 
 /**
 * A build staging strategy definition.
 *
 * Closure delegate:
 * org.artifactory.build.staging.BuildStagingStrategy - The strategy that's to be returned.
 *
 * Plugin info annotation parameters:
 * version (java.lang.String) - Closure version. Optional.
 * description (java.lang.String - Closure description. Optional.
 * params (java.util.Map<java.lang.String, java.lang.String>) - Closure parameters. Optional.
 * users (java.util.Set<java.lang.String>) - Users permitted to query this plugin for information or invoke it. 
 * groups (java.util.Set<java.lang.String>) - Groups permitted to query this plugin for information or invoke it.
 *
 * Closure parameters:
 * buildName (java.lang.String) - The build name specified in the REST request.
 * params (java.util.Map<java.lang.String, java.util.List<java.lang.String>>) - The parameters specified in the REST request.
 */
 strategyName(version, description, users, groups, params) { buildName, params ->
 }
}

replication {
    /**
     * Handle before file replication events.
     *
     * Context variables:
     * skip (boolean) - whether to skip replication for the current item. Defaults to false. Set to true to skip replication.
         * targetInfo (org.artifactory.addon.replication.ReplicationTargetInfo) - contains information about the replication target server
     *
     * Closure parameters:
     * localRepoPath (org.artifactory.repo.RepoPath) - the repoPath of the item on the local Artifactory server.
     */
    beforeFileReplication { localRepoPath ->
    }
    /**
     * Handle before directory replication events.
     *
     * Context variables:
     * skip (boolean) - whether to skip replication for the current item. Defaults to false. Set to true to skip replication.
         * targetInfo (org.artifactory.addon.replication.ReplicationTargetInfo) - contains information about the replication target server
     *
     * Closure parameters:
     * localRepoPath (org.artifactory.repo.RepoPath) - the repoPath of the item on the local Artifactory server.
     */
    beforeDirectoryReplication { localRepoPath ->
    }
    /**
     * Handle before delete replication events.
     *
     * Context variables:
     * skip (boolean) - whether to skip replication for the current item. Defaults to false. Set to true to skip replication.
         * targetInfo (org.artifactory.addon.replication.ReplicationTargetInfo) - contains information about the replication target server
     *
     * Closure parameters:
     * localRepoPath (org.artifactory.repo.RepoPath) - the repoPath of the item on the local Artifactory server.
     */
    beforeDeleteReplication { localRepoPath ->
    }
    /**
     * Handle before property replication events.
     *
     * Context variables:
     * skip (boolean) - whether to skip replication for the current item. Defaults to false. Set to true to skip replication.
         * targetInfo (org.artifactory.addon.replication.ReplicationTargetInfo) - contains information about the replication target server
     *
     * Closure parameters:
     * localRepoPath (org.artifactory.repo.RepoPath) - the repoPath of the item on the local Artifactory server.
     */
    beforePropertyReplication { localRepoPath ->
    }
    /**
     * Handle before statistics replication events.
     *
     * Context variables:
     * skip (boolean) - whether to skip replication for the current item. Defaults to false. Set to true to skip replication.
         * targetInfo (org.artifactory.addon.replication.ReplicationTargetInfo) - contains information about the replication target server
     *
     * Closure parameters:
     * localRepoPath (org.artifactory.repo.RepoPath) - the repoPath of the item on the local Artifactory server.
     */
    beforeStatisticsReplication { localRepoPath ->
    }
}