PowerShell Script Header and Parameters for Use in ScriptRunner

Author: | Reading time: 4 minutes | Category: Development, PowerShell

PowerShell-Script Header und Parameter, ScriptRunner, PowerShell-Script Code

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 Action Packs):

<# .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 Action Pack 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 UserPrincipalName 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.

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 Action Pack. 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.

PowerShell header and parameter declaration in ScriptRunner property pages

PowerShell header and parameter in ScriptRunner Reports

Using PowerShell Parameters in ScriptRunner

The parameter declaration in ScriptRunner also fulfills various tasks. In detail these are:

  • Automatic listing of all input parameters on the property page of the script (see figure above)
  • Automatic generation of input fields to preset values on the configuration page for a ScriptRunner action
  • Automatic generation of input fields on the configuration page of Scripted Queries
  • Automatic generation of input fields and their behavior on the form page for entering the values before executing a script in the Admin and Delegate App

When generating the input fields in the Admin App, two modes are distinguished:

  • 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.

Configuration and Predefinition of PowerShell parameters in ScriptRunner

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.

Auto-generation of input form in ScriptRunner Admin Web App in Run/Test mode

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 there are no headers .PARAMETER paramname, the variables are displayed instead.

PowerShell Script Auto-generation of input form in ScriptRunner Delegate Web App

For more information about PowerShell Scripting and the automatic graphical UI in ScriptRunner, contact us here.

You might also be interested in these blog posts:

ScriptRunner Github
PowerShell Script Code, PowerShell Parameter und ihre grafische Darstellung in ScriptRunner