ScriptTipp Header und Parameter

PowerShell Script Header and Parameters for Use in ScriptRunner (English)

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

 

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

 

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 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 in ScriptRunner Property Pages

 

 

PowerShell Header and Declaration 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.

Merle Siegmon

Merle Siegmon

Online Marketing Managerin bei ScriptRunner
Merle Siegmon hat mehrjährige Erfahrungen im B2B-Marketing und ist Ansprechpartnerin für alle Marketingmaßnahmen rund um ScriptRunner. Dabei bedient sie die Kommunikationskanäle von Adwords bis Social Media aus einer Hand.
Merle Siegmon