Script Creation

This section lists the APIs to create, execute and query information for script tasks. The sections document the following aspects:

  • Script task creation
  • Description and help texts
  • Task executable query

Script Task Creation

To create a script task you have to call one of the scriptTask() methods. The last parameter of the scriptTask methods can be used to set additional options of the task. Every script task needs one IScriptTaskType.

The code{ } block is required for every IScriptTask. The block contains the code, which is executed when the task is executed.

Script Task with default Type

The method scriptTask() will create a script task.
If no script task type is given, the IScriptTaskType DV_PROJECT is used.

Task creation with default type
scriptTask("TaskName"){
    code{
        // Task execution code here
    }
}

Script Task with Task Type

You could also define the used IScriptTaskType at the scriptTask() methods. The methods
  • scriptTask(String, IApplicationScriptTaskType, Action)
  • scriptTask(String, IProjectScriptTaskType, Action)
will create an script task for passed IScriptTaskType. The two methods differentiate, if a project is required or not.

Task creation with TaskType Application
scriptTask("TaskName", DV_APPLICATION){
    code{
        // Task execution code here
    }
}

Task creation with TaskType Project
scriptTask("TaskName", DV_PROJECT){
    code{
        // Task execution code here
    }
}

Multiple Tasks in one Script

It is also possible to define multiple tasks in one script.

Define two tasks is one script
scriptTask("TaskName"){
    code{ }
}

scriptTask("SecondTask"){
    code{ }
}

Script Creation with IDE Code Completion Support

Due to the fact that the IDE can not know which API is available inside of a script file, a glue code is needed to tell the IDE, what API is callable inside of a script file.

The ScriptApi.daVinci(Action) method enables the IDE code completion support in a script file. You have to write the daVinci{ } block and inside of the block the code completion is available. The following sample shows the glue code for the IDE:

Script creation with IDE support
import static com.vector.cfg.automation.api.ScriptApi.*

//daVinci enables the IDE code completion support
daVinci{

    // Normal script code here
    scriptTask("TaskName"){
        code{
             // Script task execution code here
        }
    }
}

The daVinci{} block is only required for code completion support in the IDE. It has no effect during runtime, so the daVinci{} is optional in script files (.dv.groovy)

Script Task isExecutableIf

You can set an isExecutableIf handler, which is called before the IScriptTask is executed. The code can evaluate, if the IScriptTask shall be executable. If the handler returns true, the code of the IScriptTask is executable, otherwise false. See class IExecutableTaskEvaluator for details.

The Closure isExecutable has to return a boolean. The passed arguments to the closure are the same as the code{ } block arguments.

Inside of the Closure a property notExecutableReasons is available to set reasons why it is not executable. It is highly recommended to set reasons, when the Closure returns false.

Task with isExecutableIf
scriptTask("TaskName"){

    isExecutableIf{ taskArgument ->
        // Decide, if the task shall be executable
        if(taskArgument == "CorrectArgument"){
            return true
        }
        notExecutableReasons.addReason "The argument is not 'CorrectArgument'"
        return false
    }

    code{ taskArgument ->
        // Task execution code here
    }
}

Description and Help

Script Description

The script can have an optional description text. The description shall list what this script contains. The method scriptDescription(String) sets the description of the script.

The description shall be a short overview. The String can be multiline.

Script with description
// You can set a description for the whole script
scriptDescription "The Script has a description"

scriptTask("Task"){
    code{}
}

Task Description

A script task can have an optional description text. The description shall help the user of the script task to understand what the task does. The method taskDescription(String) sets the description of the script task.

The description shall be a short overview. The String can be multiline.

Task with description
scriptTask("TaskName"){
    taskDescription "The description of the task"

    code{ }
}

Task Help

A script task can also have an optional help text. The help text shall describe in detail what the task does and when it could be executed. The method taskHelp(String) sets the help of the script task.

The help shall be elaborate text about what the task does and how to use it. The String can be multiline.

The help text is automatically expanded with the help for user defined script task arguments, see IScriptTaskBuilder.newUserDefinedArgument(String, Class, String).

Task with description and help text
scriptTask("TaskName"){
  taskDescription "The short description of the task"
  taskHelp """
          The long help text
          of the script with multiple lines

          And paragraphs ...
          """.stripIndent()
  // stripIndent() will strip the indentation of multiline strings
  // The three """ are needed, if you want to write a multiline string

    code{ }
}