Configure runbook input parameters in Azure Automation

Input types

Azure Automation supports various input parameter values across the different runbook types. Supported input types for each type of runbook are listed in the following table.

Runbook type Supported parameter inputs PowerShell - String
- Security.SecureString
- INT32
- Boolean
- DateTime
- Array
- Collections.Hashtable
- Management.Automation.SwitchParameter PowerShell Workflow - String
- Security.SecureString
- INT32
- Boolean
- DateTime
- Array
- Collections.Hashtable
- Management.Automation.SwitchParameter Graphical PowerShell - String
- INT32
- INT64
- Boolean
- Decimal
- DateTime
- Object Python - String

Configure input parameters in PowerShell runbooks

PowerShell and PowerShell Workflow runbooks in Azure Automation support input parameters that are defined through the following properties.

Property Description Required. The name of the parameter. This name must be unique within the runbook, must start with a letter, and can contain only letters, numbers, or underscore characters. Mandatory Optional. The Boolean value specifies whether the parameter requires a value. If you set this to True, a value must be provided when the runbook is started. If you set this to False, a value is optional. If you don't specify a value for the


   Mandatory

property, PowerShell considers the input parameter optional by default. Default value Optional. A value that is used for the parameter if no input value is passed in when the runbook starts. The runbook can set a default value for any parameter.

Windows PowerShell supports more attributes of input parameters than those listed above, such as validation, aliases, and parameter sets. However, Azure Automation currently supports only the listed input parameter properties.

As an example, let's look at a parameter definition in a PowerShell Workflow runbook. This definition has the following general form, where multiple parameters are separated by commas.

Param
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name1 = <Default value>,
  [Parameter (Mandatory= $true/$false)]
  [Type] $Name2 = <Default value>
Now let's configure the input parameters for a PowerShell Workflow runbook that outputs details about virtual machines, either a single VM or all VMs within a resource group. This runbook has two parameters, as shown in the following screenshot: the name of the virtual machine (VMName) and the name of the resource group (resourceGroupName).
In this parameter definition, the input parameters are simple parameters of type string.
Note that PowerShell and PowerShell Workflow runbooks support all simple types and complex types, such as Object or PSCredential for input parameters. If your runbook has an object input parameter, you must use a PowerShell hashtable with name-value pairs to pass in a value. For example, you have the following parameter in a runbook.
[Parameter (Mandatory = $true)]
[object] $FullName
In this case, you can pass the following value to the parameter.
@{"FirstName"="Joe";"MiddleName"="Bob";"LastName"="Smith"}
For PowerShell 7.1 runbooks, provide array input parameters in below format:
Value
When you do not pass a value to an optional String parameter with a null default value, the value of the parameter is an empty string instead of Null.
Configure input parameters in graphical runbooks
To illustrate the configuration of input parameters for a graphical runbook, let's create a runbook that outputs details about virtual machines, either a single VM or all VMs within a resource group. For details, see My first graphical runbook.
A graphical runbook uses these major runbook activities:
Authenticate with Azure using managed identity configured for automation account.
Definition of a Get-AzVM cmdlet to get VM properties.
Use of the Write-Output activity to output the VM names.
The Get-AzVM activity defines two inputs, the VM name and the resource group name. Since these names can be different each time the runbook starts, you must add input parameters to your runbook to accept these inputs. Refer to Graphical authoring in Azure Automation.
Follow these steps to configure the input parameters.
Select the graphical runbook from the Runbooks page and then click Edit.
In the graphical editor, click the Input and output button then Add input to open the Runbook Input Parameter pane.
The Input and Output control displays a list of input parameters that are defined for the runbook. Here you can either add a new input parameter or edit the configuration of an existing input parameter. To add a new parameter for the runbook, click Add input to open the Runbook input parameter blade, where you can configure parameters using the properties defined in Graphical authoring in Azure Automation.
Create two parameters with the following properties to be used by the Get-AzVM activity, and then click OK.
Parameter 1:
Name -- VMName
Type -- String
Mandatory -- No
Parameter 2:
Name -- resourceGroupName
Type -- String
Mandatory -- No
Default value -- Custom
Custom default value -- Name of the resource group that contains the VMs
View the parameters in the Input and Output control.
Click OK again, and then click Save.
Click Publish to publish your runbook.
Configure input parameters in Python runbooks
Unlike PowerShell, PowerShell Workflow, and graphical runbooks, Python runbooks do not take named parameters. The runbook editor parses all input parameters as an array of argument values. You can access the array by importing the sys module into your Python script, and then using the sys.argv array. It is important to note that the first element of the array, sys.argv[0], is the name of the script. Therefore the first actual input parameter is sys.argv[1].
For an example of how to use input parameters in a Python runbook, see
My first Python runbook in Azure Automation.
Arguments with spaces are currently not supported. As a workaround, you could use \\t in addition to \\n.
Assign values to input parameters in runbooks
This section describes several ways to pass values to input parameters in runbooks. You can assign parameter values when you:
Start a runbook
Test a runbook
Link a schedule for the runbook
Create a webhook for the runbook
Start a runbook and assign parameters
A runbook can be started in many ways: through the Azure portal, with a webhook, with PowerShell cmdlets, with the REST API, or with the SDK.
Start a published runbook using the Azure portal and assign parameters
When you start the runbook in the Azure portal, the Start Runbook blade opens and you can enter values for the parameters that you have created.
In the label beneath the input box, you can see the properties that have been set to define parameter attributes, for example, mandatory or optional, type, default value. The help balloon next to the parameter name also defines the key information needed to make decisions about parameter input values.
String parameters support empty values of type String. Entering [EmptyString] in the input parameter box passes an empty string to the parameter. Also, string parameters don't support Null. If you don't pass any value to a string parameter, PowerShell interprets it as Null.
Start a published runbook using PowerShell cmdlets and assign parameters
Azure Resource Manager cmdlets: You can start an Automation runbook that was created in a resource group by using Start-AzAutomationRunbook.
   $params = @{"VMName"="WSVMClassic";"resourceGroupeName"="WSVMClassicSG"}
   Start-AzAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" –ResourceGroupName $resourceGroupName -Parameters $params
Azure classic deployment model cmdlets: You can start an automation runbook that was created in a default resource group by using Start-AzureAutomationRunbook.
   $params = @{"VMName"="WSVMClassic"; "ServiceName"="WSVMClassicSG"}
   Start-AzureAutomationRunbook -AutomationAccountName "TestAutomation" -Name "Get-AzureVMGraphical" -Parameters $params
When you start a runbook using PowerShell cmdlets, a default parameter, MicrosoftApplicationManagementStartedBy, is created with the value PowerShell. You can view this parameter on the Job details pane.
Start a runbook using an SDK and assign parameters
Azure Resource Manager method: You can start a runbook using the SDK of a programming language. Below is a C# code snippet for starting a runbook in your Automation account. You can view all the code at our GitHub repository.
public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
  var response = AutomationClient.Jobs.Create(resourceGroupName, automationAccount, new JobCreateParameters
    Properties = new JobCreateProperties
      Runbook = new RunbookAssociationProperty
        Name = runbookName
      Parameters = parameters
  return response.Job;
Azure classic deployment model method: You can start a runbook by using the SDK of a programming language. Below is a C# code snippet for starting a runbook in your Automation account. You can view all the code at our GitHub repository.
public Job StartRunbook(string runbookName, IDictionary<string, string> parameters = null)
  var response = AutomationClient.Jobs.Create(automationAccount, new JobCreateParameters
    Properties = new JobCreateProperties
      Runbook = new RunbookAssociationProperty
        Name = runbookName
      Parameters = parameters
  return response.Job;
To start this method, create a dictionary to store the runbook parameters VMName and  resourceGroupName and their values. Then start the runbook. Below is the C# code snippet for calling the method that's defined above.
IDictionary<string, string> RunbookParameters = new Dictionary<string, string>();
// Add parameters to the dictionary.
RunbookParameters.Add("VMName", "WSVMClassic");
RunbookParameters.Add("resourceGroupName", "WSSC1");
//Call the StartRunbook method with parameters
StartRunbook("Get-AzureVMGraphical", RunbookParameters);
Start a runbook using the REST API and assign parameters
You can create and start a runbook job with the Azure Automation REST API by using the PUT method with the following request URI:
https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Automation/automationAccounts/{automationAccountName}/jobs/{jobName}?api-version=2017-05-15-preview
In the request URI, replace the following parameters:
subscriptionId: Your Azure subscription ID.
resourceGroupName: The name of the resource group for the Automation account.
automationAccountName: The name of the Automation account that's hosted within the specified cloud service.
jobName: The GUID for the job. GUIDs in PowerShell can be created by using [GUID]::NewGuid().ToString()*.
To pass parameters to the runbook job, use the request body. It takes the following information, provided in JSON format:
Runbook name: Required. The name of the runbook for the job to start.
Runbook parameters: Optional. A dictionary of the parameter list in (name, value) format, where name is of type String and value can be any valid JSON value.
If you want to start the Get-AzureVMTextual runbook created earlier with VMName and resourceGroupName as parameters, use the following JSON format for the request body.
      "properties":{
        "runbook":{
        "name":"Get-AzureVMTextual"},
      "parameters":{
         "VMName":"WindowsVM",
         "resourceGroupName":"ContosoSales"}
An HTTP status code 201 is returned if the job is successfully created. For more information on response headers and the response body, see create a runbook job by using the REST API.
Test a runbook and assign parameters
When you test the draft version of your runbook by using the test option, the Test page opens. Use this page to configure values for the parameters that you have created.
Link a schedule to a runbook and assign parameters
You can link a schedule to your runbook so that the runbook starts at a specific time. You assign input parameters when you create the schedule, and the runbook uses these values when it is started by the schedule. You can't save the schedule until all mandatory parameter values are provided.
Create a webhook for a runbook and assign parameters
You can create a webhook for your runbook and configure runbook input parameters. You can't save the webhook until all mandatory parameter values are provided.
When you execute a runbook by using a webhook, the predefined input parameter [WebhookData](automation-webhooks.md) is sent, along with the input parameters that you define.
Pass a JSON object to a runbook
It can be useful to store data that you want to pass to a runbook in a JSON file. For example, you might create a JSON file that contains all parameters that you want to pass to a runbook. To do this, you must convert the JSON code to a string and then convert the string to a PowerShell object before passing it to the runbook.
This section uses an example in which a PowerShell script calls
Start-AzAutomationRunbook to start a PowerShell runbook, passing the contents of the JSON file to the runbook. The PowerShell runbook starts an Azure VM by retrieving the parameters for the VM from the JSON object.
Create the JSON file
Type the following code in a text file, and save it as test.json somewhere on your local computer.
   "VmName" : "TestVM",
   "ResourceGroup" : "AzureAutomationTest"
Create the runbook
Create a new PowerShell runbook named Test-Json in Azure Automation.
To accept the JSON data, the runbook must take an object as an input parameter. The runbook can then use the properties defined in the JSON file.
Param(
     [parameter(Mandatory=$true)]
     [object]$json
# Ensures you do not inherit an AzContext in your runbook
Disable-AzContextAutosave -Scope Process
# Connect to Azure with system-assigned managed identity
$AzureContext = (Connect-AzAccount -Identity).context
# set and store context
$AzureContext = Set-AzContext -SubscriptionName $AzureContext.Subscription -DefaultProfile $AzureContext
# Convert object to actual JSON
$json = $json | ConvertFrom-Json
# Use the values from the JSON object as the parameters for your command
Start-AzVM -Name $json.VMName -ResourceGroupName $json.ResourceGroup -DefaultProfile $AzureContext
If you want the runbook to execute with the system-assigned managed identity, leave the code as-is. If you prefer to use a user-assigned managed identity, then:
From line 10, remove $AzureContext = (Connect-AzAccount -Identity).context,
Replace it with $AzureContext = (Connect-AzAccount -Identity -AccountId <ClientId>).context, and
Enter the Client ID.
Save and publish this runbook in your Automation account.
Call the runbook from PowerShell
Now you can call the runbook from your local machine by using Azure PowerShell.
Sign in to Azure as shown. Afterward, you're prompted to enter your Azure credentials.
Connect-AzAccount
For PowerShell runbooks, Add-AzAccount and Add-AzureRMAccount are aliases for Connect-AzAccount. Note that these aliases are not available for graphical runbooks. A graphical runbook can only use Connect-AzAccount itself.
Get the contents of the saved JSON file and convert it to a string. JsonPath indicates the path where you saved the JSON file.
$json =  (Get-content -path 'JsonPath\test.json' -Raw) | Out-string
Convert the string contents of $json to a PowerShell object.
$JsonParams = @{"json"=$json}
Create a hashtable for the parameters for Start-AzAutomationRunbook.
$RBParams = @{
     AutomationAccountName = 'AATest'
     ResourceGroupName = 'RGTest'
     Name = 'Test-Json'
     Parameters = $JsonParams
Notice that you're setting the value of Parameters to the PowerShell object that contains the values from the JSON file.
Start the runbook.
$job = Start-AzAutomationRunbook @RBParams
Next steps
To prepare a textual runbook, see Edit textual runbooks in Azure Automation.
To prepare a graphical runbook, see Author graphical runbooks in Azure Automation.