User Defined Arguments

A script task can create IScriptTaskUserDefinedArgument, which can be set by the user (e.g. from the commandline) to pass user defined arguments to the script task execution. An argument can be optional or required. The arguments are type safe and checked before the task is executed. An argument can be specified with a value and also without one.
Example: "--count 25" or "-s"

Possible valueTypes are:

String
Boolean
Void: For parameter where only the existence is relevant.
File: The existence of the file is not checked by default. See argument validators.
Path: Same as File
Integer
Long
Double

The help text is automatically expanded with the help for user defined script task arguments.

Script task UserDefined argument with no value

scriptTask("TaskName"){
  def procArg = newUserDefinedArgument("p", Void, "Enables the processing of ...")
  code{
      if(procArg.hasValue){
        scriptLogger.info  "The argument -p was defined"
      }
  }
}

Define and use script task user defined arguments from CLI

scriptTask("TaskName"){
  def countArg = newUserDefinedArgument("count", Integer,
                                        "The amount of elements to create")

  def nameArg = newUserDefinedArgument("name", String,
                                       "The element name to create")
  code{
      // NOTE: The value can only be retrieved within the code closure
      int count = countArg.value
      String name = nameArg.value

      scriptLogger.info  "The arguments --name and --count were $name, $count"
  }
}

Script task UserDefined argument with default value

scriptTask("TaskName"){
  //  User Defined Argument with the default value 25.0
  def procArg = newUserDefinedArgument("p", Double, 25.0, "Help text ...")
  code{
      double value = procArg.value
      scriptLogger.info  "The argument -p was $value"
  }
}

Script task UserDefined argument with multiple values

scriptTask("TaskName"){
  def multiArg = newUserDefinedArgument("multiArg", String, "Help text ...")

  code{

      List<String> values = multiArg.values  // Call values instead of value
      scriptLogger.info  "The argument --multiArg  had values: $values"
  }
}

User defined Argument Validators

You could also specify a validator for the argument to check for special conditions, like the file must exist. This is helpful to provide a quick feedback to the user, if the task would be executable. Simply add the validator at the end of the newUserDefinedArgument() call. The validator code is called when the input is checked. There are also default validators available, like:

Constraints.IS_EXISTING_FOLDER
Constraints.IS_EXISTING_FILE
Constraints.IS_VALID_AUTOSAR_SHORT_NAME

Please see chapter Constraints for more available validators.

Script task UserDefined argument with predefined validator

import  com.vector.cfg.util.contract.util.Constraints

scriptTask("TaskName"){
  def contArg = newUserDefinedArgument( "p", String,
                                        "Help text ...",
                                        Constraints.IS_VALID_AUTOSAR_SHORT_NAME_PATH )
  code{

      String value = contArg.value
      scriptLogger.info  "The argument -p was $value"
  }
}

Or you implement your own validation logic, by passing a Closure, which throws an exception, if the value is invalid.

Script task UserDefined argument with own validator

scriptTask("TaskName"){

  //  User Defined Argument with the validator code as parameter
  newUserDefinedArgument( "p", Integer, 20, "Help text ...",
                { value ->
                    if( value % 2){
                        throw new IllegalArgumentException("The value has to be even.")
                    }
                } )

  code{
  }
}

Constraints

Constraints provides general purpose constraints for checking given parameter values throughout the automation interface. These constraints are referenced from the AutomationInterface documentation wherever they apply. The AutomationInterface takes a fail fast approach verifying provided parameter values as early as possible and throwing appropriate exceptions if values violate the corresponding constraints.

The following constraints are provided:

IS_NOT_NULL

Ensures that the given Object is not null.

IS_NON_EMPTY_STRING

Ensures that the given String is not empty.

IS_VALID_FILE_NAME

Ensures that the given String can be used as a file name.

IS_VALID_PROJECT_NAME

Ensures that the given String can be used as a name for a project. A valid project name starts with a letter [a-zA-Z] contains otherwise only characters matching [a-zA-Z0-9_-] and is at most 128 characters long.

IS_NON_EMPTY_ITERABLE

Ensures that the given Iterable is not empty.

IS_VALID_AUTOSAR_SHORT_NAME

Ensures that the given String conforms to the syntactical requirements for AUTOSAR short names.

IS_VALID_AUTOSAR_SHORT_NAME_PATH

Ensures that the given String conforms to the syntactical requirements for AUTOSAR short name paths.

IS_ABSOLUTE

Ensures that Ensures that given Path is absolute.

IS_WRITABLE

Ensures that the file or folder represented by the given Path exists and can be written to.

IS_READABLE

Ensures that the file or folder represented by the given Path exists and can be read.

IS_EXISTING_FOLDER

Ensures that the given Path points to an existing folder.

IS_EXISTING_FILE

Ensures that the given Path points to an existing file.

IS_CREATABLE_FOLDER

Ensures that the given Path either points to an existing folder which can be written to or points to a location at which a corresponding folder could be created.

IS_DCF_FILE

Ensures that the given Path points to a DaVinci Developer workspace file (.dcf file).

IS_DVJSON_FILE

Ensures that the given Path points to a DaVinci project file (.dvjson file).

IS_ARXML_FILE

Ensures that the given Path points to an .arxml file.

Run Script Task with User Defined Task Arguments from CLI

The help of the run command shows, how to execute a script task with user defined arguments.

Help for run script task

Usage: dvcfg-b automation run [-h] -b=<folder> [-p=<file>]
                  -t=<task>[,<task>...] [-t=<task>[,<task>...]]...
                  [-a=<arg>]... [-l=<location>[,<location>...]]...
                  [--debugger[=<port>]] [--no-save]

Description:
Run automation tasks with arguments.

Help for user defined task arguments

* -t, --task=<task>[,<task>...]    List of script tasks to execute.
                                   E.g.: -t task1,task2
 -a, --arg=<arg>                   Define a set of arguments specific to a single task.
                                   E.g.: -a 'task1' -a '--name=str1 --value=1' -a 'task2' -a '-i 1,2,3'

Let’s have a look at an example script task with user defined arguments as shown below.

Example script task with user defined arguments

import static com.vector.cfg.automation.api.ScriptApi.*

scriptTask("userArgTask", DV_APPLICATION) {

def arg_enable = newUserDefinedArgument("enable", Void, "Help text ...")
def arg_count = newUserDefinedArgument("count", Integer, "Help text ...")
def arg_name = newUserDefinedArgument("name ", String, "Help text ...")
def arg_double = newUserDefinedArgument("double", Double, 25.0, "Help text ...")
def arg_multiArg = newUserDefinedArgument("multiArg", String, "Help text ...")

code {
    if (arg_enable.hasValue) {
        scriptLogger.info "The argument --enable was defined."
    }
    if (arg_count.hasValue) {
        scriptLogger.info "The argument --count has the value ${arg_count.value}."
    }
    if (arg_name.hasValue) {
        scriptLogger.info "The argument --name has the value ${arg_name.value}."
    }
    if (arg_double.hasValue) {
        scriptLogger.info "The argument --double has the value ${arg_double.value}."
    }
    if (arg_multiArg.hasValue) {
        List<String> values = arg_multiArg.values
        scriptLogger.info "The argument --multiArg has values: ${values}."
    }
    }
}

To run this script task from CLI, you can use the following command.

Example CLI call with user defined task arguments

automation run ...
           -t "userArgTask"
           -a "userArgTask"
           -a "--enable --count=25 --name=John --double=25.0 --multiArg=1,2,3,4,5"