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

Unix

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

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

  Code Block
  language bash title Example how use PowerShell run PowerShell® script code with a shebang linenumbers true
  #!/usr/bin/env pwsh Write-Output "Hello" Write-Output "world"

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

  Code Block
  language bash title Example how to pass a variable to subsequent jobs with Windowsrun PowerShell® script code from a single line linenumbers true
  pwsh -NoLogo -NonInteractive -Command '& { Echoecho "Hello"; Echoecho "World"; }'

  Explanation:

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

• An even more weird way

  how to add

  of running PowerShell® code

  to a

  from JS7 job

  script

  scripts includes:

  Code Block
  language bash title Example how to pass a variable to subsequent jobs with Windowsrun PowerShell® script code from a number of lines linenumbers true
  pwsh -NoLogo -NonInteractive -Command '& { ` Echo "Hello"; ` Echo "World"; ` }'

  Explanation:

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

Solution

• To address the problem of special characters use base64 encoding for variable values as this encoding results in a single printable string.
• To address the limitation concerning the size of environment variables do not use them and think about ways how to directly append lines to the temporary file indicated by JS7_RETURN_VALUES. 

Example

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

  Code Block
  language bash title Example how to run PowerShell® script code from a file linenumbers true
  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

  Let's assume two jobs to be executed in sequence:
• The first job creates a lengthy e-email body in HTML format,
The second job sends e-mail and makes use of the HTML body. Find a number of possible implementations for the JS7 job script

:

Code Block
language bash title Example

for Shell version using environment variables on Unix

how run PowerShell® script code with a shebang replacement linenumbers true

@@setlocal enabledelayedexpansion & @@findstr/v "^@@[fs].*&" "%~f0" | powershell.exe -NonInteractive -Command - & exit !errorlevel!/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 if using a version > 5.1 please change powershell.exe to pwsh.exe:

  @@setlocal enabledelayedexpansion & @@findstr/v "^@@[fs].*&" "%~f0" | pwsh.exe -NonInteractive -Command - & exit !errorlevel!/b&

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

  Code Block
  language bash title Example how to run PowerShell® script code from a single line linenumbers true

  #!/user/bin/env bash
  
  mailBody="<html><body><b>hello</b> <i>world</i></body></html>"
  mailBodyEncoded=$(echo $mailBody | base64)
  echo "body=base64:$mailBodyEncoded" >> $JS7_RETURN_VALUES

  Code Block
  language bash title Example for Shell version using files on Unix
  #!/user/bin/env bash echo "<html><body><b>hello</b> <i>world</i></body></html>" > /tmp/mail-body.html echo "body=base64:$(cat /tmp/mail-body.html | base64)" >> $JS7_RETURN_VALUES

  Code Block
  language bash title Example for PowerShell version on Unix
  #!/usr/bin/env pwsh $mailBody = "<html><body><b>hello</b> <i>world</i></body></html>" $mailBodyEncoded = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes( $mailBody )) "body=base64:$mailBodyEncoded" | Out-File $env:JS7_RETURN_VALUES -Append

  Code Block
  title Example for PowerShell version on Windows (multi-line)
  @@findstr/v "^@@f.*&" "%~f0"|pwsh.exe -&goto:eof $mailBody = "<html><body><b>hello</b> <i>world</i></body></html>" $mailBodyEncoded = [System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes( $mailBody )) "body=base64:$mailBodyEncoded" | Out-File $env:JS7_RETURN_VALUES -Append

  Code BlocktitleExample for PowerShell version on Windows (single-line)

  pwsh.exe -NoLogo -NonInteractive -Command "& { Echo ""

  body=base64:$([System.Convert]::ToBase64String([System.Text.Encoding]::UTF8.GetBytes( '<html><body><b>hello</b> <i>world</i></body></html>' )) )"" | Out-File $env:JS7_RETURN_VALUES -Append

  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:

  Code Block
  language bash title Example how to run PowerShell® script code from a file linenumbers true
  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

• In fact the e-mail body is not too lengthy, however, it suggests that an e-mail body of arbitrary size would be imported by some template file as e.g. for PowerShell with $mailBody = Get-Content "mail-body.html"

  • The above bash version with files and the PowerShell version both work with arbitrary length values.
• Base64 encoding is available from a number of sources such as the base64 Unix utility or the .NET Core class.
• The value of the body variable is prefixed with base64: to indicate the encoding.
The subsequent JS7 - JITL MailJob accepts the body variable, identifies the encoding and automatically decodes the argument value.