Task Options

Description

The Task Options are values that can be specified from the  2  Status Panel Options section bafore the execution of a Task.

It provides variability as to what the Task does. The values are also passed to the Task Parameters function so there can be some dynamic adaption of the execution environment based on the options selected.

The values are persisted from run to run in the options.json.txt file described in Folder Structure.

The presence of function options([Task]$task) inside the Task Execution Script indicates the Options panel should be created and populated with the various option input mechanisms specified in the options function.

There are 7 valid types for specifying the Option values. The type property is used to specify the type. They all result in a single entry into the Options hashtable passed to the Task Parameters.

Allowable Properties

• type='val' - The option type where val is one of input, check, radio, combo, file, folder or exec

• parm='val' - val is the key used in the created hashtable

• label='val' - val is the label that is displayed on the GUI panel requesting input

• place='val' - val is placeholder text when there is no value for parm in the hashtable. Used only with type='input'

• regex='val' - val is a Regex string used to vaklidate the entries. Typically used to force numeric input. Used only with type='input'

• valset='val' - val is used to populate combo or radio types. val is a comma separated list of pairs where each pair is a '/' separated value/display value string. If the value begins with '*' it is the default or initial value. If there is only one value in the pair the value is also the displayed value.

• auto=$true - Used with type='exec' to automatically start the program at the conclusion of running the Task.

• exec='val' - Used with type='exec' to supply the file name that is used by the program being started.

Option Input

The type='input' returns a string as the value in the hashtable. The keyword is the value of parm.

The optional regex='str' property can be used to validate the input string where str us a valid Powershell Regex expression.

Example with no validation

$opts += @{type='input';  parm='genstr';  label='GenStr';  place='string to generate'}

Example with validation that ensures input value is a numeric integer

$opts += @{type='input';  parm='gen';     label='Gen';     place='number of lines to generate'; regex='^[0-9]+$'}

Option Checkbox

The parm keyword is added to the hashtable with a $null value which passes a boolean switch to the called program.

Example - if set will pass -bool1 to the called program. If not set, nothing is passed.

$opts += @{type='check';  parm='bool1';   label='bool1';   place='turns on bool1 option when checked'}

Option Radio

The user chooses one of the displayed strings. The parm keyword's value is the paired value. If the value is empty the keyword is not added to the hashtable. A leading value of * is removed but flags the choice as the default initial choice.

Example. A choice of no trap passes no parameter. A choice of gen FAIL passes -trap fail and a choice of gen TRAP passes -trap trap.

$opts += @{type='radio';  parm='trap';    label='trap';    valset='*/*no trap,fail/gen FAIL,trap/gen TRAP'}

Option Combo

The user chooses one of the displayed strings. The parm keyword's value is the paired value. If the value is empty the keyword is not added to the hashtable. A leading value of * is removed but flags the choice as the default initial choice.

Example. A choice of --none-- passes no parameter. A choice of green passes -combo green. and a choice of show red passes -combo red and a choice of set blue passes -combo blue.

$opts += @{type='combo';  parm='combo';   label='combo';   valset='*/*--none--,green,red/show red,blue/set blue'}

Option Folder

Example with no validation

Option File

Example with no validation

Option Exec

Example of starting Excel program

$opts += @{type='exec';   parm='exec';     auto=$true; exec="$($task.ExecLocn)\out-docs\demo-excel.xlsx";  label='Start Excel';}

To support this, the following function equivalent needs to be added. This example starts Excel and modifies the initial sheet depending on a global value.

The stopApplicationProgram function is required to stop a program that may have previously been started. It uses a global to know if it was previously started.

 function startApplicationProgram([Task]$task,[string]$name) {
   $tfs = $task.tfs;
   $what = $tfs.globMap.demoGlobs.excelRun;
   hlogBoth("startApplicationProgram invoked $name what $what")
   $sheet = $null;
   switch($what) {
     "basic"    {$sheet = "formats"}
     "cloner"   {$sheet = "cloned"}
     "chart"    {$sheet = "chart"}
     "regress"  {$sheet = "index"}
     "hello"    {$sheet = "sample-sales"}
   }
   if ($sheet -ne $null) {
     $ExcelDoc = new-Object -ComObject Excel.Application
     $ExcelDoc.visible = $true
     $WorkBook = $ExcelDoc.Workbooks.Open("$name");
     $sheetObj = $WorkBook.Sheets.Item($sheet); # select specific sheet
     $sheetObj.Activate();
     $ExcelDoc.WindowState = "xlMinimized"; #this trick brings window in focus
     $ExcelDoc.WindowState = "xlNormal";
     return  $ExcelDoc;
   } else {
     return $null;
   }
 }

 function stopApplicationProgram([object]$task,[object]$commObj) {
   [string]$name = $task.startAppOpts.exec;
   hlog("cond stop $name")
   if ($commObj -ne $null) {
     hlog("stopping $name");
     $ExcelDoc = $commObj;
     $ExcelDoc.DisplayAlerts = $false;
     $ExcelDoc.Quit();
   }
   return $null;
 }

Example Option Function

An example of a typical options function follows. The resulting hashtable is passed to the params function. Note the return value of ,$opts to prevent Powershell from returning a list.

  function options([Task]$task) {
    $opts = @();
    $opts += @{type='input';  parm='gen';     label='Gen';     place='number of lines to generate'; regex='^[0-9]+$'}
    $opts += @{type='input';  parm='genstr';  label='GenStr';  place='string to generate'}
    $opts += @{type='check';  parm='bool1';   label='bool1';   place='turns on bool1 option when checked'}
    $opts += @{type='radio';  parm='trap';    label='trap';    valset='*/*no trap,fail/gen FAIL,trap/gen TRAP'}
    $opts += @{type='combo';  parm='combo';   label='combo';   valset='*/*--none--,green,red/show red,blue/set blue'}
    return  ,$opts
  }