PowerShell Script Header and Parameters for use in ScriptRunner

As a programming language, PowerShell of course supports header information for scripts. While the headers have no meaning for interactive application in the PowerShell console or PowerShell ISE, the opposite is true for PowerShell scripts. Even parameter inputs, as known from PowerShell cmdlets, must be declared as input parameters in the script. Microsoft recommends using both script headers and parameter declarations in its best practices for PowerShell scripting. For these and other reasons, this article takes a look at the PowerShell script header and how it affects the way ScriptRunner works.

PowerShell Script Header Best Practices

The script header contains various information to improve the readability and traceability of scripts. The following header information is used in the script collections for ScriptRunner (the ScriptRunner ActionPacks):

<# 
.SYNOPSIS
    A summary of how the script works and how to use it.

.DESCRIPTION 
    A long description of how the script works and how to use it.
 
.NOTES 
    Information about the environment, things to need to be consider and other information.

.COMPONENT 
    Information about PowerShell Modules to be required.

.LINK 
    Useful Link to ressources or others.
 
.Parameter ParameterName 
    Description for a parameter in param definition section. Each parameter requires a separate description. The name in the description and the parameter section must match. 
#>

A practical example: PowerShell Script Header of the Copy-ADUser script from the ScriptRunner ActionPack for Active Directory.

<# 
.SYNOPSIS 
    Copy a Active Directory account, properties and group memberships. 

.DESCRIPTION 

.NOTES 
    This PowerShell script was developed and optimized for ScriptRunner. The use of the scripts requires ScriptRunner. The customer or user is authorized to copy the script from the repository and use them in ScriptRunner. The terms of use for ScriptRunner do not apply to this script. In particular, AppSphere AG assumes no liability for the function, the use and the consequences of the use of this freely available script. PowerShell is a product of Microsoft Corporation. ScriptRunner is a product of AppSphere AG. © AppSphere AG
 
.COMPONENT 
    Requires Module ActiveDirectory
 
.LINK 
    https://github.com/scriptrunner/ActionPacks/tree/master/ActiveDirectory/Users 

.Parameter OUPath 
    Specifies the AD path 

.Parameter SourceUsername 
    Display name, SAMAccountName, DistinguishedName or user principal name of Active Directory user 

.Parameter GivenName 
    Specifies the new user's given name
 
.Parameter Surname 
    Specifies the new user's last name or surname 

.Parameter Password 
    Specifies the password value for the new account
 
.Parameter DomainAccount 
    Active Directory Credential for remote execution without CredSSP 

.Parameter SamAccountName 
    Specifies the Security Account Manager (SAM) account name of the new user 

.Parameter UserPrincipal
    Name Specifies the user principal name (UPN) in the format @.
 
.Parameter NewUserName 
    Specifies the name of the new user 

.Parameter DisplayName 
    Specifies the new user's display name 

.Parameter EmailAddress 
    Specifies the user's e-mail address 

.Parameter CopyGroupMemberships 
    Copies the group memberships too
 
.Parameter ChangePasswordAtLogon 
    Specifies whether a password must be changed during the next logon attempt
 
.Parameter DomainName 
    Name of Active Directory Domain 

.Parameter SearchScope 
    Specifies the scope of an Active Directory search
 
.Parameter AuthType 
    Specifies the authentication method to use 
#>

Best Practices for Declaring PowerShell Parameters

In PowerShell scripts you use parameter declarations. These define and structure the input for the PowerShell script. The declaration is summarized in a block and is called a param block or parameter section.

The parameter names in the declaration must match the name for the variable in the header. A parameter declaration usually contains the type of the variable and its name. In addition, further properties can be defined for the use of the variable and the permitted input options.

The parameter declaration for the practical example is shown below:

param(
[Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [string]$OUPath,
[Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [string]$SourceUsername,
[Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [string]$GivenName,
[Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [string]$Surname,
[Parameter(Mandatory = $true,ParameterSetName = "Local or Remote DC")]
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [string]$Password,
[Parameter(Mandatory = $true,ParameterSetName = "Remote Jumphost")] [PSCredential]$DomainAccount,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$SAMAccountName,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$UserPrincipalName,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$NewUserName,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$DisplayName,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$EmailAddress,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [switch]$CopyGroupMemberships,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [switch]$ChangePasswordAtLogon,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [string]$DomainName,
[Parameter(ParameterSetName = "Local or Remote DC")]
[Parameter(ParameterSetName = "Remote Jumphost")] [ValidateSet('Basic', 'Negotiate')] [string]$AuthType="Negotiate" 
)

Now that both the Script Header and the PowerShell parameters have been defined, the effects of these two blocks in ScriptRunner are shown below.

Using the PowerShell Script Header in ScriptRunner

The Script Header performs several tasks in ScriptRunner:

• Automatic filling of a description field for the script. The header .SYNOPSIS is copied into this field. If this header does not exist or is empty, the header .DESCRIPTION will be used and automatically shortened if necessary. ScriptRunner takes over the annoying filling in of description fields. The description field can be overwritten manually without changing the script header.
• Automatic filling of a description field for a ScriptRunner action that uses this script. The description is taken from the script properties.
• Automatic display of the header .NOTES and notes about the ActionPack. These can be found on the properties page of the script and the action in which the script is used.
• Automatic display of a short description on the form input page when performing an action in the web apps for administrators, operators and end users.
• Automatic filling of the cause description in the report of an executed action, if there was no other cause code at the start of the action. This also ensures that a reference to the intended function, which the script is to execute is always available in the report and for evaluations.
• Automatic display of the header .PARAMETER paramname as descriptive title of the generically created input field in the Admin and Delegate App form.

Contents of the Script Header are used for, among other things, descriptions of scripts and actions.

Information from the Script Header is also displayed in the Action Report

Using PowerShell Parameters in ScriptRunner

The parameter declaration also performs several tasks in ScriptRunner. Specifically, these are:

• Automatic listing of all input parameters on the script’s property page (see figure above).
• Automatically generate input fields to pre-populate values on the configuration page for a ScriptRunner action.
• Automatic generation of input fields on the configuration page of scripted queries
• Automatically generate input fields and their behavior on the form page to pre-populate values before running a script in the Admin and Delegate App

Two modes are distinguished when generating the input fields in the Admin App:

• Edit Mode
• Run / Test Mode

In both modes, in addition to the headers .SYNOPSIS and .PARAMETER, the parameter names or variables of the param block itself are also displayed. In Edit mode, the parameters can be both preset and locked with values. Locked values thus act as constants with fixed values. The behavior of the parameter types from the declaration is taken into account.

In ScriptRunner, the order of the parameters in the declaration also determines the order of the automatically generated form fields in the input masks. ScriptRunner also interprets known variable types and format information. Thus, parameters with the additional properties „Mandatory“ become mandatory input fields, „ValidateSets“ become dropdown menus, „ValidateRange“ and „ValidateLength“ check user input, etc.

Additional format information is considered in the Run/Test mode of the Admin App. In the practical example here, this is the property „mandatory“. Parameters that have been preset in Edit Mode are displayed with the filled-in default value. Parameters that have been locked are no longer displayed in Run mode because they have already been assigned fixed values.

In Run / Test Mode of the Admin App additional format information is taken into account, e.g. the mandatory property

There is only one display for the Run mode in the Delegate App. This is largely also the case for the Admin App. However, there are two important differences:

• The parameter or variable names are not displayed to the user.
• If no .PARAMETERparamname headers exist, the variables are displayed instead.

View of an action in the Delegate App

If you want to get more information about PowerShell Scripting and the automatic graphical UI in ScriptRunner, please contact us!