JS7 JobScheduler

Space shortcuts

Page tree

Introduction

  • PowerShell® is a frequently used scripting language available for Linux, MacOS, Windows and other platforms.
  • JS7 offers the JS7 - PowerShell Module for simplified access to the JS7 - REST Web Service API
  • This article explains how to syntactically include PowerShell® scripts with JS7 job scripts

Invoking PowerShell

PowerShell is an interpreter that has to be invoked and to which related script code is passed.

Unix

  • Find the below examples for download (.json upload): pdRunPowerShell4Unix.workflow.json

  • In order to directly run PowerShell® script code from a JS7 shell job script the recommended approach is to use a shebang like this:

    Example how run PowerShell® script code with a shebang
    #!/usr/bin/env pwsh
 
Write-Output "Hello"
Write-Output "world"

  • As a bad alternative the PowerShell® executable can be invoked directly and can be parameterized like this

    Example how to run PowerShell® script code from a single line
    pwsh -NoLogo -NonInteractive -Command '& { echo "Hello"; echo "World"; }'

    Explanation:

    • Consider the quoting: when using the -Command parameter then the PowerShell® script has to be specified from a string. This includes:
      • quoting the script by single quotes.
      • quoting code inside the script with double quotes or using escape characters for single quotes.
    • Note that each PowerShell® command has to be terminated with a semicolon.

  • An even more weird way of running PowerShell® code from JS7 job scripts includes:

    Example how to run PowerShell® script code from a number of lines
    pwsh -NoLogo -NonInteractive -Command '& { `
  Echo "Hello"; `
  Echo "World"; `
}'

    Explanation:

    • Note the use of single quotes, double quotes and semicolons as in the previous example. 
    • In addition each line of script code has to be terminated with a backtick for line continuation.

  • In addition, a PowerShell® script can be executed from a file that is in reach of the JS7 Agent:

    Example how to run PowerShell® script code from a file
    pwsh -NoLogo -NonInteractive -File some_powershell_script.ps1
  • For any above ways how to call PowerShell® consider to activate the setting Fail on output to stderr that is available from the Job Options tab of a job's properties in the Configuration view.: PowerShell is far from perfect in reporting exit codes, for example when exceptions are raised then this will not return a non-zero exit code to the Windows shell calling PowerShell®. Instead a job's output to the stderr channel has to be checked to make an order fail in case of PowerShell® exceptions.

Windows

  • Find the below examples for download (.json upload): pdRunPowerShell4Windows.workflow.json

  • In order to directly run PowerShell® script code from a JS7 shell job script the recommended approach is to use a shebang replacement like this:

    Example how run PowerShell® script code with a shebang replacement
    @@setlocal enabledelayedexpansion & set f=%RANDOM%.ps1 & @@findstr/v "^@@[fs].*&" "%~f0" > !f! & powershell.exe -NonInteractive -File !f! & set e=!errorlevel! & del /q !f! & exit !e!/b&

Write-Output "Hello" 
Write-Output "world"

    Explanation:

    • If you consider this shebang replacement somewhat cryptic then add it to JS7 - Script Includes which are easily referenced from shell jobs, e.g. by using ##!include pwsh
    • The PowerShell® pwsh.exe executable is available starting with PowerShell 6.0. PowerShell releases 5.x use the executable powershell.exe that can be used with the shebang accordingly. 

      Therefore when using a version > 5.1 please change powershell.exe to pwsh.exe:

      @@setlocal enabledelayedexpansion & set f=%RANDOM%.ps1 & @@findstr/v "^@@[fs].*&" "%~f0" > !f! & pwsh.exe -NonInteractive -File !f! & set e=!errorlevel! & del /q !f! & exit !e!/b&

  • As a bad alternative the PowerShell® executable can be invoked directly and can be parameterized like this:

    Example how to run PowerShell® script code from a single line
    pwsh.exe -NoLogo -NonInteractive -Command "& { Echo ""Flight Destination: $env:FLIGHT_DESTINATION""; Echo ""Booking Code: $env:BOOKING_CODE""; }"

    Explanation:

    • Consider the quoting: when using the -Command parameter then the PowerShell® script has to be specified from a string. This includes:
      • quoting the script by double quotes.
      • quoting code inside the script with two double quotes or using single quotes.
    • Note that each PowerShell® command has to be terminated with a semicolon.


  • In addition, a PowerShell® script can be executed from a file that is located in reach of the JS7 Agent:

    Example how to run PowerShell® script code from a file
    pwsh.exe -NoLogo -NonInteractive -File some_powershell_script.ps1
  • For any above ways how to call PowerShell® consider to activate the setting Fail on output to stderr that is available from the Job Options tab of a job's properties in the Configuration view.: PowerShell is far from perfect in reporting exit codes, for example when exceptions are raised then this will not return a non-zero exit code to the Windows shell calling PowerShell®. Instead a job's output to the stderr channel has to be checked to make an order fail in case of PowerShell® exceptions.

Accessing Arguments

Arguments to jobs can be provided by a number of sources such as workflow variables, order variables, Job Resource variables and job arguments. PowerShell jobs are of type "shell" and can acess arguments from environment variables.

Find the example of a workflow that declares the flight_destination and booking_code workflow variables like this:


The job is passed environment variables that are assigned the values of related workflow variables like this:


The job can access environment variables in its job script using the syntax $env:VARIABLE like this:

Passing Arguments

Dynamic variables can be created by a job and can be passed to subsequent jobs. Such variables use names that are different from workflow variables, order variables, Job Resource variables and job arguments.

In its job script the job can create dynamic variables like this:

  • The Add-Content cmdlet is used to append name/value pairs to a temporary file.
    • The syntax for the cmdlet's -Value argument is:  -Value "<name>=<value>"
  • The temporary file is provided by JS7 and is accessible from the path indicated by the JS7_RETURN_VALUES environment variable.
  • There are a number of ways how to add content to a file, however as PowerShell did change encodings during a number of versions, the recommended way for Unix/Windows is use of the Add-Content cmdlet.


Subsequent jobs access dynamic variables from environment variables that are assigned the values of newly created dynamic variables like this:

Examples

Above examples are available for download (upload .json): pdPowerShellArguments.workflow.json