Product Knowledge Base

Space shortcuts

Page tree

Update Information

  • This article is deprecated and applies to JobScheduler releases up to 1.9
  • Starting from JobScheduler Release 1.10.5 native support for PowerShell is available
  • For detailed information see PowerShell Jobs
    FEATURE AVAILABILITY STARTING FROM RELEASE 1.10.5

There are at least two different approaches to pass parameters to a PowerShell script:

  • as command line arguments
  • as environment variables

As an example for both methods we will use a simple script which will list the content of a folder, filtered by a given filename extension. The parameters are defines in an order like this:

 <order title="Executes the script ListFilesByExtension.ps1">
    <params>
        <param name="Script_Filename"    value="ListFilesByExtension.ps1"/>
        <param name="FolderName"         value="c:\temp"/>
        <param name="FileNameExtension"  value=".txt"/> 
    </params>
    <run_time let_run="no"/>
 </order>

FolderName ist the name of the folder that should be listed and FileNameExtension is the value of the extension that will be selected.

The script code, without the initialisation of the parameters, is given below:

 $Dir = .....
 $Ext = .....
 
 $a = "List $Dir with Extension $Ext `n" + "==========================";
 $a
 
 # Filenames as a list
 GCI $Dir -R | Where \{$_.Extension -EQ $Ext\} | sort-Object -descending Length | Format-List -property *

Using Command Line Parameters

Using Position Parameters

  powershell.exe ... -file "%SCHEDULER_PARAM_SCRIPT_FILENAME%" "%SCHEDULER_PARAM_FolderName%" "%SCHEDULER_PARAM_FileNameExtension%"

 $Dir = $args[0]
 $Ext = $args[1]
 ...

We do not recommend using parameters like this:

  • Depending on the parameters every job will be different. 
  • No general solution for a generic PowerShell job is possible. This will increase the effort for maintenance of jobs.
  • In Addition, accessing a parameter by its position can lead to errors 
    • if  someone changes the command line arguments without adjusting the script or 
    • if the same script will be used by different jobs with different command line arguments.
  • The better approach is to use the parameters by name.

Using Named Parameters

Starting a script like below:

    .\CreateVariablesFromEnvironment.ps1 -Prefix "SCHEDULER_PARAM_"

and the first statement in the script is the param statement:

 param ([string] $Prefix)

will fill the variable Prefix with the Value SCHEDULER_PARAM_.

Using Environment Variables

JobScheduler provides parameters of jobs and orders as environment variables to a shell.

Using Explicit Variables

The command line that is used to start the script, would not make use of additional parameters for the script:

 powershell.exe ... -file "%SCHEDULER_PARAM_SCRIPT_FILENAME%"

Instead, the script retrieves the parameter values by reading the environment variable for each parameter (see How to pass parameters from JobScheduler to a PowerShell script):

 $Dir = $env:SCHEDULER_PARAM_FolderName
 $Ext = $env:SCHEDULER_PARAM_FileNameExtension
 .
 ...

Defining all required variables at the beginning of the script will give one an overview, which variables are used from JobScheduler. In other words, this could be part of an integrated automatic documentation.

Using by parsing all environment variables

JobScheduler provide more environment variables as the one which are related to a parameter. it is possible to get all this variables as "internal" named variables into the powerscript.

The script below shows how it works:

 # .SYNOPSIS
 #     Creates global PowerShell variables from environment variables
 # .PARAMETER Prefix
 #     Only environment variables with this prefix are converted. The prefix is cut off from
 #     the variable name
 # .Example
 #     .\CreateVariablesFromEnvironment
 #
 #     All environment variables will be converted, e.g. VAR_TEST will become $VAR_TEST
 # .Example
 #     .\CreateVariablesFromEnvironment -Prefix "SCHEDULER_PARAM_"
 #
 #     All environment variables beginning with VAR_ will be converted, e.g. VAR_TEST will become $TEST

 param ([string] $Prefix) 
 # $Prefix = "SCHEDULER_PARAM_"
 
 $envVariables = @(dir env:$Prefix*)
 foreach($envVar in $envVariables)
 {
     $name = $envVar.Name    
     $name = $name.Substring($Prefix.Length)    
     Set-Variable -name $name -value $envVar.Value -Scope Global
 }

Executing this script standalone or as part of another script it will parse all environment variables and create for each variable with the prefix SCHEDULER_PARAM_ a PowerShell variable. For example, the environment variable SCHEDULER_PARAM_FOLDERNAME is then accessible by the script as $FOLDERNAME. 

  • The advantage of using parameters from environment variables is that access to parameters is effected by the name of the parameter, not by its position on the command line.
  • This would allow to create a generic job to run PowerShell scripts.

Related Downloads

See also