For those who often delegate (PowerShell-) tasks that require user input, there is always one factor you can’t control and that is the end-user skills: even with detailed explanation and help there can and will happen errors.
PowerShell provides a few options to validate your input and prevent input-errors. ScriptRunner processes these options and gives the end-user great visibility on the validity of the input before executing the script, next to that it will prevent the execution of the script if the criteria are not met.
In the following paragraphs, I will discuss two options to validate user input with PowerShell & ScriptRunner.
The first option for validating parameters in PowerShell is the ValidateSet-attribute. It allows you to specify a set of valid values for a parameter or variable and additionally enables tab completion in the shell. This eliminates the risk of erroneous and wrong input from the en-user, since the input options are predefined.
ScriptRunner furthermore increases usability by translating this validation option to a nice drop-down menu.
Let us examine the parameter block below. We want to specify a pre-defined set of possibilities for the “memory” variable, in our example 8Gb, 16Gb or 32Gb.
The ValidatePattern -attribute allows you to specify a regular expression int the parameter block of your script that is matched with the parameter or variable value your end-user enters.
PowerShell will throw an error if the content of the variable does not match the regular expression. ScriptRunner Delegate and Self-Service App will indicate the error through a red exclamation mark at the respective input element and will prevent script execution until the error is fixed.
Introduction to regular expressions (regex)
A regular expression is a sequence of characters that define a search pattern. Regex is known to be a bit tricky, so be sure to use the correct syntax. Below, you’ll find a short overview of the syntax used in our examples.
Anchors are characters that specify the boundaries of the expression:
indicates start of string or line
indicates end of string or line
With placeholders, you describe which characters you expect your search result to match to:
matches the character a
e. g. matches any character in the a-z range”
e. g. matches any character that is not in the a-z range
w or [a-zA-Z_0-9]
matches any word character
With quantifiers, you can specify how many times the characters defined through the placeholders are part of your pattern.
At least n but no more than m times
1 or more times
0 or more times
0 or one time
Example of a regular expression
Let’s try a simple example: we want to validate a string that only matches letters of the alphabet.
Here’s one possibility how we can achieve this through regular expressions:
In the table below, you’ll find the expression divided into its separate parts, to make it clearer what is happening:
Start of string
All character in the a-z range
1 or more times the character range
End of string
Regex validation in PowerShell
When the expression is shaped, we can use it to validate string variables in PowerShell.
Several PowerShell operators (e.g. -match, -split, -replace) as well as cmdlets (select-string) are supporting regex.
Keep in mind that PowerShell regex expressions are by default case-insensitive. If you want to make them case-sensitive use the ‘c’ in the operators (e.g. -cmatch, -csplit, -creplace, as seen in figure 2).
Figure 2: Examples for regex validation in PowerShell
Using regex with PowerShell and ScriptRunner: first example
We’ll start with our expression from the regex-introduction. We want to validate a string that only matches the letters of the alphabet.
In our PowerShell script we define ValidatePattern as following:
When running this script as an Action within ScriptRunner, the parameter $OnlyLetters can be easily validated. If the validation fails, an exclamation mark is displayed and the execute button is grayed-out. Below you can find a few validation tests (figures 3a-c):
Figure 3a: After validating the input for $OnlyLetters, ScriptRunner displays an error warning, since the input contains numbers, which are prohibited through the regular expression.
Figure 3b: After validating the input for $OnlyLetters, ScriptRunner displays an error warning, since the input contains spaces, which are prohibited through the regular expression.
Figure 3c: After validating the input for $OnlyLetters, ScriptRunner accepts the input, because it only contains alphabetical characters
Using regex with PowerShell and ScriptRunner: advanced second example
Another example from the field is validating a User login name in Active Directory. The maximum length by design is 20 characters and a lot of characters are prohibited ( /[:;|=,+*?<>]’“.) , next to that every company is using their own naming conventions.
Here’s an example from a customer, the User login name should comply to the following rules:
Length is 10-15 characters
No numeric characters
Only special char allowed is “-“
Must start with u-
Now, let’s translate these requirements into a regular expression:
And, as you can see in figures 4 a-e, the validation works!
Figure 4a: After validating the input for $UserLoginName, ScriptRunner displays an error warning, since the input contains too few characters.
Figure 4b: After validating the input for $UserLoginName, ScriptRunner displays an error warning, since the input string doesn’t start with “u-“.
Figure 4c: After validating the input for $UserLoginName, ScriptRunner displays an error warning, since the input contains numbers.
Figure 4d: After validating the input for $UserLoginName, ScriptRunner displays an error warning, since the input contains the special character “$”.
Figure 4e: After validating the input for $UserLoginName, ScriptRunner accepts the input, since it’s conforming with the rules defined in the regular expression.
As you can see, parameter validation is no rocket science at all, if you get these basics right. With just a minor timeinvestment you will get fewer errors and save time and nerves in the long run. Of course, there are many more ways to make the use of PowerShell scripts safe and secure. You can find an overview in the free webinar Using PowerShell Scripts with more security.
Bruno Buyck is the founder of Trouble Shooter a company that specializes in PowerShell automation. The past decade Bruno delivered workshops on how to manage and automate systems with PowerShell. He has hundreds of script running in production environments which results in over 34 Million script executions every year. He loves to teach and prove that PowerShell is “What The Fuck”.