/src/main/java/com/onresolve/jira/groovy/canned/CannedScript.java

package com.onresolve.jira.groovy.canned;



import com.atlassian.jira.util.ErrorCollection;



import java.util.List;

import java.util.Map;



/**

 *

 */

public interface CannedScript {

    /**

     * Returns the human-readable name of the script, eg "Awesome Script"

     * @return name of the script

     */

    String getName();



    /**

     * Returns a longer description which is displayed under the script name.

     * The return value is printed as in, so you can include html tags. You will need to

     * escape anything that needs escaping

     * @return description of the script

     */

    String getDescription();



    /**

     * Returns a list of categories which determine where in the UI this script will be displayed.

     * Currently valid categories are: ["Condition", "Validator", "Function", 'ADMIN']

     * You must provide at least one of these strings, more than one is also OK

     * @return list of categories

     */

    List getCategories();



    /**

     * Return a list of parameters required to run this script.

     * Each parameter is a map, and should at a minimum have a Name and Label key.

     * Type can be one of list, radio, shorttext, mediumtext, text, checkboxes.

     * For list, radio and checkbox types the Values key should return a Map of key->value options

     * See the shipped scripts for more details.

     * @param params Currently selected parameters, to allow for a wizard-type interface

     * @return selected values

     */

    List<CannedScriptArg> getParameters(Map params);



    /**

     * This is run before the script is run for real, and is responsible for sanity checking

     * the input arguments. It should return an {@link ErrorCollection} with field-specific and/or

     * general errors.

     *

     * @param params User selected inputs

     * @param forPreview set when the user has clicked the Preview button, but not when run by the workflow engine

     * @return An {@link ErrorCollection} or null

     */

    ErrorCollection doValidate(Map params, boolean forPreview);



    /**

     * The actual function provided by the built-in script.

     * @param params Input arguments specified by the user

     * @return No specific requirements here, however Conditions should set passesCondition to

     * true/false appropriately. If the return has a key "output" then the value of this

     * is shown in the Admin panel

     */

    Map doScript(Map params);



    /**

     * This mis-named method is called when the user clicks Preview, and the output of this is used as

     * the workflow function representation.

     * @param params User selected inputs

     * @param forPreview True when using the Admin panel, false when being called from a workflow functions page

     * @return An HTML preview string, eg what the script would actually do if the user clicked Run.

     */

    String getDescription(Map params, boolean forPreview);



    /**

     * This is for wizard, or multi-step UIs. Have a look at the examples for usages.

     * @param params User selected inputs

     * @return true if no other inputs are required, false otherwise.

     */

    Boolean isFinalParamsPage(Map params);

}