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.
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. #>
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:
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:
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!
https://www.scriptrunner.com/wp-content/uploads/2021/04/scriptrunner-version2020r3.png10001000Frank Kressehttps://www.scriptrunner.com/wp-content/uploads/2018/05/ScriptRunner_Logo_RGB-300x45.pngFrank Kresse2021-04-27 17:19:072021-05-06 13:33:05ScriptRunner 2020R3 – full scope of functions in the portal, multi-attribute queries and more actions for end usersScriptRunner Software GmbH
https://www.scriptrunner.com/wp-content/uploads/2021/03/sr-vorschau-produktjahr.png10001000Frank Kressehttps://www.scriptrunner.com/wp-content/uploads/2018/05/ScriptRunner_Logo_RGB-300x45.pngFrank Kresse2021-03-09 10:00:512021-03-26 15:44:12Preview of the product year 2021