Basic Principles of Graphic Representation for Input Parameters

With PowerShell On-board Resources

PowerShell does not offer a satisfactory solution for the problem of graphic representation. As a „home remedy“, you can encode WPF forms or use extensive XAML code. As practice has shown, however, this variant has many disadvantages:

1. A separate miniprogram (usually a compiled EXE) is created at the end for each script. The execution requirements of these miniprograms do not differ from a script . The person carrying out the task must be allowed to execute PowerShell and must work in the rights context necessary for script execution.
2. The miniprograms must be distributed to the user. This can be done with software distribution systems, resulting in complex procedures that need to be followed. If you have accessed a script with your browser and started it from there, you won’t want to miss it anymore.
3. It does not allow the delegation of a task with clear separation of the rights. Obviously, no security-conscious administrator or manager would like to see PowerShell administrators working in the service desk or at the end users.
4. WPF and especially XAML code in the script lead to a confusing, mixed „monster code“. Many administrators cannot and do not want to write, maintain, or develop such code. In addition, such solutions are extremely error-prone based on experience in the PowerShell community.
5. The „graphical overhead“ must be tested with every change to the script. This quickly leads to losses in agility and quality assurance becomes much more complex than necessary.

With ScriptRunner

The ScriptRunner Admin and Delegate App is specifically designed for administrators and service desk staff who want to use PowerShell scripts in daily IT operations with a graphical interface.

The following features were at the centre of the design and development:

• Automatic generation of graphical input forms from the PowerShell scripts themselves, without coding, without having to configure assignments, and with automatic adaptation in the event of script changes.
• Automatic assignment of typical and known display options such as fields, switches, different drop-down menus, date and time displays etc. to the different parameter types
• Automatic application of additional validation options of extended type declarations
• Automatic display of field descriptions and notes on the use of the script
• Dynamicy selection and search for input values for the PowerShell parameters using queries, including cascaded logic.
• Display of actual values using queries. For example, you can display the properties of a user in the AD in the form as you are used to. You can overwrite and change these values directly in the form.
• Input parameters of a script can already be preassigned for execution. The default values can be changeable or not changeable (fixed).
• The input form created should remain as clear as possible even with many input parameters.
• The script starts after filling in the form
• Confirmation of the result and view of the generated report
• Easy display and use of forms and functions in all popular browsers (IE11, Edge, Chrome, Firefox, Opera)

To map these helpful functions, ScriptRunner operates in a simplified way according to the following principles:

• All scripts in the Script Repository are regularly checked for changes and parsed in the background. Defective scripts are marked in the admin app in the list of scripts, queries and actions.
• Parsing generates metadata for each PowerShell script on the ScriptRunner host. This contains all information about the script header and parameter declaration. Changes to the script also cause changes to the metadata.
• Some metadata, such as the list of parameters in the param block and the descriptions in the script header, are displayed on the appropriate wizard pages. The synopsis or the descriptions from the header are automatically included in the description for the script and the action. They can be changed or removed there. Changes are not written back to the script.
• ScriptRunner defines different display objects and display options. These provide the basis for form generation.
• When creating, calling or changing an action in the Admin or Delegate App, the display functions of ScriptRunner are merged with the metadata of the script at runtime, the form is generated and displayed. The real-time generation ensures that a current form matching the script is always generated and displayed. It is therefore not necessary to assign parameters to fields. No „finished“ forms are saved either.
• The form display distinguishes between two modes that differ partially in detailed behavior. The EDIT mode of an action is used to configure it. Not all extended display options are used. In the RUN mode of an action, in contrast, all extended display options are used for the form.

ScriptRunner automatically generates input forms for PowerShell parameters

From these basic principles, several conditions and best practices for script development are derived:

• It is absolutely necessary to use a script header and a param-block for the input parameters in the script. This should contain the description and instructions for the use of the script and individual input parameters.
• Absolutely necessary parameters are defined first in the param block. They are thus automatically displayed first in the input form.
• The Admin App displays a corresponding form field with variable name and description for each input parameter.
• The Delegate App displays a corresponding form field with description for each input parameter. If the description is missing, the otherwise invisible variable name is displayed instead.
• Extended parameter and type declarations should be used to use different display options for the input mask as well as for input validation.
• Fixed input parameters are hidden from the form in RUN mode because the user cannot make any changes to them.
• To create a clear input form even for complex scripts with many (but not always necessary) input parameters, unused parameters should be hidden by the fixed default value with an empty value.
  
  
  

Representation of PowerShell data types in ScriptRunner

PowerShell has built-in support for data types for parameters. The common input of input parameters on the command line is based on the type string. PowerShell can convert the String input type to different other types depending on the declared script parameter. If no type is declared, PowerShell converts to a suitable format depending on the notation.

Best practice: Use the declaration of data types in PowerShell, since type-free conversion is often the cause of processing problems in the script and cmdlets.

The generic display in the ScriptRunner apps supports and checks valid value ranges for the following data types:

• All string types
• Number types: byte, sbyte, short, ushort, int, uint, long, ulong, Int16, UInt16, Int32, UInt32, Int64, UInt64, System.Int16, System.UInt16, System.Int32, System.UInt32, System.Int64, System.UInt64; checks these for valid number and number range input
• Boolean types: switch
• Array types: String Arrays and Number Type Arrays
• Credentials: PSCredential, securestring
• Date/Time Types: DateTime, TimeSpan

ScriptRunner displays the mentioned data types in the generic browser interface of the Admin App and the Delegate App. The type of display in the Admin App also depends on whether an action is to be configured (EDIT mode) or started (RUN mode).

Display with extended PowerShell parameter declarations

Alongside pure data type declaration, PowerShell allows an extended parameter declaration. This is mainly used for validation functions of the input and its sequence. ScriptRunner supports the declarations listed in the table. This has the following advantages:

1. Different, extended display options for the inputs are available. For example, simple dropdown menus, dropdown menus with multiple selections, check boxes, DatePicker, etc. are also possible.
2. Extended input check already in the input form and before starting the script. The script can only be started after valid input the.
3. Forced entries for defined parameters are marked with a red frame. The script can only be started after valid selection or input.
4. Prevents incorrect input and execution of a script.

The display options in the Admin App also depend on their attributes.

An example:

<# .SYNOPSIS An example for the generic display of input parameters with different data types and extended parameter declarations in ScriptRunner Admin and Delegate App .PARAMETER MyString Please enter a simple string .PARAMETER MyStringSelect Please select one of the simple strings .PARAMETER MyUintArray Please enter several numbers, separated by comma .PARAMETER MyStringArray Please select multiple strings, use CTRL Click .PARAMETER MyNumber Please enter a Number .PARAMETER MySwitch Please select the box .PARAMETER MyCredential Please select a Credential #> param ( [Parameter(Mandatory=$true)] #this input is mandatory [ValidateLength(5, 10)] #only min 5 and max 10 chars allowed [string]$MyString, [Parameter(Mandatory=$true,Position=4)] #this param will displayed on fourth position [ValidateSet('first','second','third')] #only these values are allowed [string]$MyStringSelect, [ValidateRange(7, 18)] #the input min/max per value is allowed, comma separated [uint16[] ]$MyUintArray, [ValidateSet('one','two','three','four')] #only this values are allowed, multiple selection possible [string[]]$MyStringArray, [Parameter(Position=2)] [ValidateRange(2018,2023)] #the input of minimum 2018 and maximum 2023 is allowed [int]$MyNumber, [switch]$MySwitch, #defines a switch [PSCredential]$MyCredential #defines a PowerShell credential parameter )

The application of this script header leads to the display of the different properties in the automatically generated form.

In the EDIT mode of the ScriptRunner Admin App, the order and possible default values are checked in the script itself. A check for „mandatory“ is not useful in this mode and therefore not possible.

All values can now be preset manually or by dropdown etc. via configuration. Default values appear directly in the input form in RUN mode, but can still be changed by the user. If the option ‚cannot be changed at script runtime‘ is set at the parameter, the default value is used as a fixed value. The form in RUN mode is shortened by this parameter in the display. This is based on the principle that non-changeable values should no longer be displayed. In this case, the user concentrates completely on the input fields that are still open.

The display and selection of the data type [PSCredential] is only possible in EDIT mode.

The RUN mode of the admin app is used to test the settings and script execution, which is why the input fields in this mode behave analogously to the Delegate App. In this mode, the check for „mandatory“ is made first. These fields are shown with a red frame and an exclamation mark if they are still empty, i.e. no value has been entered. Afterwards, each field is validated during input. Notes on validation are displayed directly in the input field if it is empty.

If invalid values are entered or if the validation algorithm detects an error, the corresponding field is framed in red.

The script can also not be started if there are missing or incorrect entries. The corresponding ok or run button is inactive. This prevents starting scripts with wrong or unauthorized input values, which would lead to an error in execution.

Display and validations in the Delegate App are analogous to RUN mode in the Admin App.

Display of Parameter Sets

Additonal options are provided by parameter sets, which were originally introduced in PowerShell to map a use case differently in a PowerShell cmdlet. In combination with scripts and ScriptRunner, this leads to very interesting additional options.

An example: Users have different properties in the AD. In addition to simple information such as phone number, department etc. there is status information such as „locked“ or „inactive“. If all these possibilities are combined in one script „Change User“, parameter sets can be used to map different use cases.

The script header below shows three use cases:

• Change the user information of a user account -> parameter set ‚Change‘
• Unlock a user account -> parameter set ‚Unlock‘
• Deactive and activate a user account -> parameter set ‚EnableDisable‘.

<# .SYNOPSIS Change a user's properties. .PARAMETER UserName Select the user account to change. .PARAMETER Unlock Unlock the user account. .PARAMETER Enable Enable/Disable the user account (Keep | Enable | Disable). .PARAMETER City Change the city (AD 'l' property) .PARAMETER Department Change the department (AD 'department' property) .PARAMETER StreetAddress Change the office street address (AD 'streetAddress' property) .PARAMETER OPhone Change the office phone number (AD 'telephoneNumber' property) #> [CmdletBinding()] Param ( [Parameter(Mandatory=$true)] [string]$UserName, [Parameter(Mandatory=$false, ParameterSetName="Unlock")] [switch]$Unlock, [Parameter(Mandatory=$false, ParameterSetName="EnableDisable")] [ValidateSet('Keep', 'Enable', 'Disable')] [string]$Enable = 'Keep', [Parameter(Mandatory=$false, ParameterSetName="Change")] [string]$City, [Parameter(Mandatory=$false, ParameterSetName="Change")] [string]$Department, [Parameter(Mandatory=$false, ParameterSetName="Change")] [string]$StreetAddress, [Parameter(Mandatory=$false, ParameterSetName="Change")] [string]$OPhone )

Now you can configure three cases with one and the same script in ScriptRunner. The distinction is made by selecting the parameter set in the respective action. The respective parameter set for the use cases can already be defined in the EDIT mode of the Admin App. If no parameter is specified, the user can select the parameter set in the Delegate App or in the RUN of the Admin App.

 

Different use cases in actions per parameter set

The displayed input form changes dynamically with the selection of the respective parameter set. If the parameter set has already been specified in the configuration, the appropriate form for the case appears for the user.

As a result, you have defined three actions that implement different use cases. In the application, each use case automatically receives a suitable form with the necessary input fields. Input fields that do not belong to the use case or parameter set are hidden.

Three use cases in the Delegate App, realized with a script and parametersets

 

Using Queries

A consistent continuation in the use of input parameters results from the use of ScriptRunner Queries. This does not require any changes to the script itself, only appropriate configurations need to be made.

In EDIT mode, the Admin App is assigned a previously configured query to an input parameter. The task of the query is to „get“ a selection list for the respective input parameter at runtime. The list of the determined input values appears in the form as a dropdown. If the input parameter is declared as an array, a drop-down appears with the option of multiple selection.

Assign a query to an input parameter, here as a dependent cascade

In the query configuration, you can also specify whether a search field and a search function should appear. The search field has two tasks:

• Pre-Search – The search is parameterized for the search process. Entering „Mü“ in a user query results in a list of all users with „mü“ in the defined attribute, e.g. in the name.
• Post-Search – An interactive search now takes place in the result set of the executed query. The input of „Mümm“ now filters all matches out of the result list „mü“.

In combination with corresponding attribute queries, the attributes of values can already be displayed.