Task Execution Script

Description

The Task Execution Script file provides parameters and context to the underlying PSEC system that manages the execution of the Task.

What it provides is dependent on the Task Type.

Execution Script File format

The script file is a valid Powershell script file whose extension type should be .psm1.

It is dynamically loaded and the function defineFlowTask is called and returns the script block itself that is then inspected using the values provided by Export-ModuleMember -Variable * -Function * statement.

Previous versions of PSEC used the variables returned. PSEC-V4 only uses the functions as this allows values to change based on contextual data that the script may be dependent on.

Class Objects Passed to Functions

The function prototype statement passes objects Flow and Task. These are defined in flow-classes.psm1.

Supported Function Signatures

The following function signatures are supported. If necessary, their contextual use is explained in the link given with each description.

getTaskDesc

function getTaskDesc([Task]$task)

This function returns a short string (100 chars or less) that describes what the Task does. It can use the $task object to vary the string based on context.

runScript

function runScript([Task]$task,[hashtable]$parms,[hashtable]$status)

Called for types Manual and Script

It executes the actual task.

primeContextTask

function primeContextTask([Task]$task)

The existence of this function makes it a Context Task whose function is to set context variables that other tasks can reference.

For this reason it is expected that it is the first task in a Workflow.

fetchJavaMain

function fetchJavaMain([Task]$task,[hashtable]$parms)

This function is required for type=java Tasks.

It returns a full Java class string that should be started. It can use the $task object or the $parms to vary the returned string based on context.

The current Java class string can be seen by right clicking on the ≡ symbol in the top right of the  2  Status Panel

fetchJavaClassStr

function fetchJavaClassStr([Task]$task,[hashtable]$parms)

This function is required for type=java Tasks.

It is used to dynamically create a class path string passed to the Java program.

It expects a ';' separated list of folders. Values that begin with $env: are replaced with the environment value.

If the referenced folder contains .class files, the folder name is retained as part of the class path. Otherwise, the folder is iterated through and all .zip and .jar are added to the class path (in descending age sequence).

Since the class path is dynamically created, .jar or .zip libraries can be added to the folder and it will be part of the class path when the Task is next executed.

The current class path can be seen by right clicking on the ≡ symbol in the top right of the  2  Status Panel.

params

function params([Task]$task,[hashtable]$htOpts)

The processing of the params function is described at Task Parameters.

The current parameters can be seen by right clicking on the ≡ symbol in the top right of the  2  Status Panel.

options

function options([Task]$task)

The processing of the options function is described at Task Options.

The current parameters (which may be affected by Options settings) can be seen by right clicking on the ≡ symbol in the top right of the  2  Status Panel.

fetchManualSteps

function fetchManualSteps([Task]$task)

Returns an array of step names that represent the manual steps to be performed.

All steps need to be marked as complete before the Task is deemed GOOD.

showWhen

function showWhen([Task]$task)

Returns $true when the Task should be visible.

Returns $false when the Task should be invisible.

Useful in context settings when, for example, quarterly Tasks have to be run.

startApplicationProgram

function startApplicationProgram([Task]$task,[string]$name)

Used, along with the exec Option to automatically start an application program. This is useful, for example, to restart Excel when the Task is rewriting a file that Excel is reading.

Refer to Option Exec to see an example implementation.

stopApplicationProgram

function stopApplicationProgram([Task]$task,[object]$commObj)

Used as a partner with startApplicationProgram to stop a started program when the Task run starts.

Refer to Option Exec to see an example implementation.

Sample Execution Script File

Below is a sample .psm1 file that executes a Java Task type.

# demo-options

set-strictmode -version 2.0

function defineFlowTask([Flow]$flow,[Task]$task) {
#--- define
  $def = new-module -asCustomObject -scriptBlock {
    # shows how to present contextual variables
    function getTaskDesc([Task]$task) {
      $tfs = $task.tfs;
      [string]$desc        = @"
This illustrates options capability of the PSEC workflow subsystem.`r`n
Current Values: cycleNo=$($tfs.globMap.demoGlobs.cycleNo) month=$($tfs.globMap.demoGlobs.month)`r`n
"@
      return $desc;
    }

    function fetchJavaMain([Object]$task,[hashtable]$parms) {
      return 'org.srp.psec.TestArgsPsec'
    }

    function fetchJavaClassStr([Object]$task,[hashtable]$parms) {
      return '$env:PSEC_V4_UTILS/srp-util/lib;$env:PSEC_V4_UTILS/srp-util/java-gen-prod/production/srp-util;$env:PSEC_V4_UTILS/gael-core/lib;$env:PSEC_V4_UTILS/gael-core/libaux;'
    }

    # ---------- define task parameters
    <#
    The $htOpts parms has the processed options.  It can be modified or used to do
    other changes to the setup.
    #>
      function params([Object]$task,[hashtable]$htOpts) {
        #$tfs = $task.tfs;
        $date = Get-Date
        [string]$dateStr = $date.ToString("yyyyMMdd")

        $htOpts.datestr = $dateStr;
        $htOpts.brief   = "$($task.statlocn)"
        return  $htOpts
      }

      # ---------- define task options
      function options([Task]$task) {
        $opts = @();

        #$tfs = $task.tfs;
        $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
      }

      Export-ModuleMember -Variable * -Function *

  }
  return $def;
}

Etc