Implementing Your Own Runbook Input Parameter Validation Checking

Using the “Initialize Data” activity at the beginning of a runbook allows you to provide input parameters to any runbook. This greatly enhances the flexibility of a runbook by allowing it to be called by another runbook or via the web service, and the input parameters supplied to vary the data being used inside the runbook. However, the Initialize Data activity doesn’t allow you to specify whether parameters are required or optional and doesn’t provide any value checking to validate the data being passed in before it’s used by the runbook. Here’s where the power of PowerShell can come in handy!

In PowerShell, you can define function parameters with lots of different validation options. When using PowerShell in the Run .NET Script activity, you can use this validation to your advantage by essentially creating a function header that defines how you want to validate your runbook input parameters. You can use nearly all of the validation options in the Run .NET Script activity. The only ones that won’t apply are the ones that have to do with null values and collections (since all the input parameters will be strings or numbers).

(Note: For more info about function parameters and validation, see the TechNet documentation.)

Here’s a list of the validation types you can use (I’ll show some examples below):

[AllowEmptyString()]
[ValidateCount(1,5)]
[ValidateLength(1,10)]
[ValidatePattern("[0-9][0-9][0-9][0-9]")]
[ValidateRange(0,10)]
[ValidateScript({$_ -ge (get-date)})]
[ValidateSet("Low", "Average", "High")]
[ValidateNotNullOrEmpty()]

You can also use the Mandatory=$true|$false and ParameterSetName options on the Parameter attribute to define whether parameters are optional or not and whether they are grouped into different parametersets.Of course, I thought about creating a custom activity that would allow specifying parameter names, validation type and specific validation for each parameter, but I thought that would end up being kind of clunky. Sometimes, it’s easier just writing a script for what you need. So I came back around to the Run .NET Script activity and wrote a custom PowerShell function with parameters to validate the runbook input parameters.

In the example below, the Run .NET Script activity has a custom function checks four parameters: “ComputerName”, “ComputerOwner”, “IPAddress” and “FloorNumber”. In this hypothetical example,

image

The function validates that either a computer name or IP address was entered (one or the other is required). If a computer name is entered, an optional user name can be entered, but it must be one of three specific names. Optionally, the user can enter a floor number, but it must be a number between 2 and 15..

function Validate-Parameters
{
    [CmdletBinding()]
    param(
        [parameter(Mandatory=$true, ParameterSetName="Computer")]
        [ValidateNotNullOrEmpty()]
        [String] $ComputerName,

        [parameter(Mandatory=$false, ParameterSetName="Computer")]
        [ValidateSet("Bob", "Mary", "Joe")]
        [String] $ComputerOwner = "",

        [parameter(Mandatory=$true, ParameterSetName="IP")]
        [ValidatePattern("(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)")]
        [String] $IPAddress,

        [parameter(Mandatory=$false)]
        [ValidateRange(2,15)]
        [Int] $FloorNumber
            
    )
    Write-Output "Validation succeeded"
}

$cmd = "Validate-Parameters "
if ($computerName -ne "")
{
    $cmd += ‘ -ComputerName $($computerName)’
}
if ($computerOwner -ne "")
{
    $cmd += ‘ -computerOwner $($computerOwner )’
}
if ($IPAddress -ne "")
{
    $cmd += ‘ -IPAddress $($IPAddress)’
}
if ($FloorNumber -ne "")
{
    $cmd += ‘ -FloorNumber $($FloorNumber)’
}
$Output = iex -Command $cmd

Now you just add the input parameters from the previous activity as PowerShell variables:

image

If the parameters fail validation, PowerShell will throw an exception, causing the activity to fail. If the Run .NET Script activity fails, the link conditions will cause the Send Platform Event activity to run. That activity is configured like this:

image

When you pull in the Error summary text, you get a good error message that tells you how the parameter validation failed.

image

So there you have it… you can take this and cut and paste it into any runbook and simply modify the parameter validation to suit your own runbook’s parameters. Now you have a good way to validate runbook parameters using potentially complex rules by using the power of PowerShell!