Starting a Runbook from Another Runbook

Updated: May 13, 2016

Applies To: Windows Azure Pack for Windows Server, System Center 2012 R2 Orchestrator

It is a best practice in Service Management Automation to write reusable, modular runbooks with a discrete function that can be used by other runbooks. A parent runbook will often call one or more child runbooks to perform required functionality. There are two ways to call a child runbook, and each has distinct differences that you should understand so that you can determine which will be best for your different scenarios.

• Invoking a Child Runbook Using Inline Execution

• Starting a Child Runbook Using Cmdlet

To invoke a runbook inline from another runbook, you use the name of the runbook and provide values for its parameters exactly like you would use an activity or cmdlet. All runbooks in the same Service Management Automation environment are available to all others to be used in this manner. The parent runbook will wait for the child runbook to complete before moving to the next line, and any output is returned directly to the parent.

When you invoke a runbook inline, it runs in the same job as the parent runbook. There will be no indication in the job history of the child runbook that it ran. Any exceptions and any stream output from the child runbook will be associated with the parent. This results in fewer jobs and makes them easier to track and to troubleshoot since any exceptions thrown by the child runbook and any of its stream output are associated with the parent runbook’s job.

When a runbook is published, any child runbooks that it calls must already have a published version. This is because Automation builds an association with any child runbooks when a runbook is compiled. If they aren’t, the parent runbook will appear to publish properly, it but will generate an exception when it’s started. If this happens, you can republish the parent runbook in order to properly reference the child runbooks. You do not need to republish the parent runbook if any of the child runbooks are changed because the association will have already been created.

The parameters of a child runbook called inline can be any data type including complex objects, and there is no JSON serialization as there is when you start the runbook using the Management Portal or with the Start-SmaRunbook cmdlet.

The following example invokes a test child runbook that accepts three parameters, a complex object, an integer, and a boolean. The output of the child runbook is assigned to a variable.

$vm = Get-VM –Name "MyVM" –ComputerName "MyServer"  
$output = Test-ChildRunbook –VM $vm –RepeatCount 2 –Restart $true  

You can use the Start-SMARunbook cmdlet to start a runbook as described in To start a runbook with Windows PowerShell. When you start a child runbook from a cmdlet, the parent runbook will move to the next line as soon as the job is created for the child runbook. If you need to retrieve any output from the runbook, then you need to access the job using Get-SMAJobOutput.

The job from a child runbook started with a cmdlet will run in a separate job from the parent runbook. This results in more jobs than invoking the workflow inline, increasing overhead on the worker server, and making them more difficult to track. The parent can start multiple child runbooks though without waiting for each to complete. For that same kind of parallel execution calling the child runbooks inline, the parent runbook would need to use the parallel keyword.

Parameters for a child runbook started with a cmdlet are provided as a hashtable as described in Runbook Parameters. Only simple data types can be used, although you can provide the name of a credential asset as described in Credentials. If the runbook has a parameter with a complex data type, then it must be called inline.

The following example starts a child runbook with parameters and then waits for it to complete. Once completed, its output is collected from the job by the parent runbook.

$webServer = 'https://MyServer'  
$port = 9090  
$runbookName = "Test-Runbook"  
$params = @{"VMName"="MyVM";"RepeatCount"=2;"Restart"=$true}   
  
$job = Start-SmaRunbook –WebServiceEndpoint $webServer –Port $port –Name $runbookName –Parameters $params  
  
$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  

The following table summarizes the differences between the two methods for calling a runbook from another runbook.

To start a runbook with Windows PowerShell
Runbook Authoring [SMA]
Automation Runbooks