Starting a Runbook

Updated: May 13, 2016

Applies To: Windows Azure Pack for Windows Server

You can start a runbook in Service Management Automation using one of the following three methods.

• Management Portal

• PowerShell

• From another runbook

The first two methods are documented below. Calling a runbook from another runbook is documented in Starting a Runbook from Another Runbook.

1. In the Management Portal, select Automation in the left pane.

2. Select the Runbooks tab.

3. Select a runbook, and then click Start.

4. If the runbook has parameters, you will be prompted to provide values with a text box for each parameter. Boolean and datetime parameters have special selectors instead of the standard text box. See Runbook Parameters below for further details on parameters.

5. Either select View Job next to the Starting runbook message or select the Jobs tab for the runbook to view the job’s status.

You can use the Start-SmaRunbook to start a runbook with Windows PowerShell. The following sample code starts a runbook called Test-Runbook.

$webServer = 'https://MyServer'  
$port = 9090  
$runbookName = "Test-Runbook"  
Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName  

Start-SmaRunbook returns a job object that you can use to track its status once the runbook is started. You can then use this job object with Get-SmaJob to determine the status of the job and Get-SmaJobOutput to get its output. The following sample code starts a runbook called Test-Runbook, waits until it has completed, and then displays its output.

$webServer = 'https://MyServer'  
$port = 9090  
$runbookName = "Test-Runbook"  
  
$job = Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName  
  
$doLoop = $true  
While ($doLoop) {  
   $job = Get-SmaJob –WebServiceEndpoint $webServer –Port $port -Id $job.Id  
   $status = $job.Status  
   $doLoop = (($status -ne "Completed") -and ($status -ne "Failed") -and ($status -ne "Suspended") -and ($status -ne "Stopped")   
}  
  
Get-SmaJobOutput –WebServiceEndpoint $webServer –Port $port -Id $job.Id –Stream Output  

If the runbook requires parameters, then you must provide them as a hashtable where the key of the hashtable matches the parameter name and the value is the parameter value. The following example shows how to start a runbook with two string parameters named FirstName and LastName, an integer named RepeatCount, and a boolean parameter named Show. For additional information on parameters, see Runbook Parameters below.

$webServer = 'https://MyServer'  
$port = 9090  
$runbookName = "Test-Runbook"  
  
$params = @{"FirstName"="Joe";"LastName"="Smith";"RepeatCount"=2;"Show"=$true}  
Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName –Parameters $params  

Parameters are values that a runbook requires when it is started. For example, a runbook that creates a new virtual machine would presumably have a parameter for you to specify the computer name. If a parameter is mandatory, then you must provide a value for it when you start the runbook. If a parameter is not mandatory, then can provide a value but are not required to.

When you start a runbook using the Management Portal or Windows PowerShell, the instruction is sent through the Automation web service. This service does not support parameters with complex data types. If you need to provide a value for a complex parameter, then you must call it inline from another runbook as described in Starting a Runbook from Another Runbook.

The Automation web service will provide special functionality for parameters using certain data types as described in the following sections.

Named Values

If the parameter is data type [object], then you can use the following JSON format to send it a list of named values: {"Name1":Value1, "Name2":Value2, "Name3":Value3}. These values must be simple types. The runbook will receive the parameter as a PSCustomObject with properties that correspond to each named value.

Consider the following test runbook that accepts a parameter called user.

Workflow Test-Parameters  
{  
   param (   
      [Parameter(Mandatory=$true)][object]$user  
   )  
    if ($user.Show) {  
        foreach ($i in 1..$user.RepeatCount) {  
            $user.FirstName  
            $user.LastName  
        }  
    }   
}  

The following text could be used for the user parameter.

{"FirstName":"Joe","LastName":"Smith","RepeatCount":2,"Show":true}  

This results in the following output.

Joe  
Smith  
Joe  
Smith  
  

Arrays

If the parameter is an array such as [array] or [string[]], then you can use the following JSON format to send it a list of values: [Value1,Value2,Value3]. These values must be simple types.

Consider the following test runbook that accepts a parameter called user.

Workflow Test-Parameters  
{  
   param (   
      [Parameter(Mandatory=$true)][array]$user  
   )  
    if ($user[3]) {  
        foreach ($i in 1..$user[2]) {  
            $ user[0]  
            $ user[1]  
        }  
    }   
}  

The following text could be used for the user parameter.

["Joe","Smith",2,true]  

This results in the following output.

Joe  
Smith  
Joe  
Smith  
  

Credentials

If the parameter is data type [PSCredential], then you can provide the name of a Service Management Automation credential asset. The runbook will retrieve the credential asset with the name that you specify.

Consider the following test runbook that accepts a parameter called credential.

Workflow Test-Parameters  
{  
   param (   
      [Parameter(Mandatory=$true)][PSCredential]$credential  
   )  
   $credential.UserName  
}  

The following text could be used for the user parameter assuming that there was a credential asset called "MyCredential".

MyCredential  

Assuming the username in the credential was jsmith, this results in the following output.

jsmith  

Service Management Automation
Runbook Operations (old) [SMA]
Starting a Runbook from Another Runbook