PowerShell Parameter grafische Darstellung ScriptRunner

PowerShell parameters and their graphical representation in ScriptRunner (English)

A very important and customer-friendly feature of ScriptRunner is the graphical interface for entering PowerShell parameters in the Admin and Delegate App. Easy-to-use input is an essential requirement for all customers in day-to-day IT operations. The PowerShell scripts map a variety of business logic for automation and delegation. However, the scripts should not be used on the command line, but via an easy-to understand graphical interface. This article shows you how to use PowerShell parameters in the input forms and how to design them. If you consider these suggestions, your users will thank you!

 

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 generates input forms automatically

ScriptRunner automatically creates 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).

 

PowerShell Data Type

Representation in the Admin App

Representation in the Delegate App

String types

Text input field

Text input field

Number types

Text input field with check for number type and value range

Text input field with check for number type and value range

Array types

Text input field for multiple values with separators

Text input field for multiple values with separators

[switch]

Tick mark

Tick mark

[DateTime]

DatePicker

Version 2018R3

DatePicker

Version 2018R3

[TimeSpan]

Not implemented yet

Not implemented yet

[PSCredential]

Dropdown selection of credentials stored in ScriptRunner or a password store

Dropdown selection of credentials stored in ScriptRunner or a password store

[securestring]

Text input field switchable plain text display, hidden display

Version 2018R3

Text input field with hidden display

Version 2018R3


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.

PowerShell Declaration

Admin App in EDIT Mode

Admin App in RUN Mode and Delegate App

Generally also without extended declaration

The parameter can be preset with a value. The input is checked for a valid value range depending on the data type. The value can be changed by the user or is permanently assigned.

The input is checked for a valid value range depending on the data type. The input field for predefined parameters is hidden.

[Parameter (Mandatory=$true)]

The input field is marked with a gray sign. The parameter can be preset with a value.

The input field is shown with a red frame and red warning sign. The script cannot be started without valid input or selection.

[Parameter (Position=n)]

The input field is positioned at the nth position in the display sequence.

The input field is positioned at the nth position in the display sequence.

[ValidateRange(min,max)]

The input field checks entries for compliance with the specified minimum and maximum values. If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

The input field checks entries for compliance with the specified minimum and maximum values. If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

[ValidateLenght(min,max)]

The input field checks inputs for compliance with the specified minimum and maximum value for the character length.
If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

The input field checks inputs for compliance with the specified minimum and maximum value for the character length.
If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

[ValidateSet(‚a‘,’b‘,’c‘)]

The input field appears as a dropdown menu with the values a, b and c. In combination with array types, a dropdown with multiple selection is displayed.
If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

The input field appears as a dropdown menu with the values a, b and c. In combination with array types, a dropdown with multiple selection is displayed.
If the input is incorrect, the input field is marked with a red frame and the script cannot be started.

 

An example:

 

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.

PowerShell ScriptRunner Parameter

Parameter display in the Admin App 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.

ScriptRunner Parameter run PowerShell

In the RUN mode of the Admin App all validations are done

 

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

 

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.

Use Cases ScriptRunner PowerShell Parameter

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.

Parameter ScriptRunner PowerShell

Three Use Cases in the Delegate App, realized with one script and parameter sets

 

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.

 

Parameter ScriptRunner PowerShell

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.

PowerShell ScriptRunner Input forms

Input form with automatically queried actual values

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