Starting Runbook with PowerShell

To start an orchestrator runbook with PowerShell, Microsoft provide a reliable script in its MSDN web site.


But, as prerequisite, the script needs the GUIDs for runbook and runbook parameters. There are different ways to find these GUIDs. One of the easier is to use Excel, and more specifically the PowerPivot plugin. Thank you System Center Central for this tip, it works very well…


Here are the steps to retrieve data and start a runbook with PowerShell

  • Connecting Excel to the Orchestrator Web Service
  • Retrieving the GUID of the Runbook using PowerPivot
  • Retrieving the GUIDs of the Runbook Parameters using PowerPivot
  • Retrieving and updating the Sample Script provided by Microsoft
  • Running the Script



1. Find GUIDs of Runbook and parameters

Finding GUIDs for the Runbook and its parameters can be done easily using Excel and PowerPivot.

Power Pivot is an add-in allowing to perform data analysis in Excel.

This add-in is not enabled by default.

To enable PowerPivot:

  • Open Excel
  • Go to File > Options > Add-Ins
  • In the Manage box, click COM Add-ins > Go
  • Select “Microsoft Office PowerPivot”, click OKThe ribbon now has a Power Pivot tab.


Now that PowerPivot is installed, it can be used to retrieve GUIDs of the Runbook and its parameters.

First, connect the Orchestrator Web Service with Excel:

  • Launch Excel using an account with access rights on the orchestrator server
  • Go to the PowerPivot tab
  • Click on the Manage button, to open the tool




Select the From Other Sources button to launch the Table Import Wizard



Select Other Feeds

Click Next



Type a friendly name for the connection

Type the Data Feed URL, generally like http://servername:81/Orchestrator2012/orchestrator.svc

Click Test Connection



If the test is successful, click OK, then Next



Select Runbooks

Select RunbookParameters

Click Finish



Tables are imported

Click Close


Runbook ID

Go to the Runbooks worksheet



On the Name column, filter on the runbook name and select it



Copy the Runbook ID (GUID)




Parameters ID

Go to the RunbookParameters worksheet



On the RunbookId column, filter on the runbook ID and select it



Copy the Runbook Parameters ID (GUID)




2. Create the PowerShell Script

Microsoft provides a sample PowerShell script for initiating runbooks from outside Orchestrator:

Create a ps1 script using the following code:

# Details of the runbook we are going to run
$rbid = "00000000-0000-0000-00000000000000001"  
$rbParameters = @{"00000000-0000-0000-00000000000000002" = "This is the value for Param1.";" 00000000-0000-0000-00000000000000003" = " This is the value for Param2."}

# Create the request object
$request = [System.Net.HttpWebRequest]::Create("http://")

# Set the credentials to default or prompt for credentials
$request.UseDefaultCredentials = $true
# $request.Credentials = Get-Credential

# Build the request header
$request.Method = "POST"
$request.UserAgent = "Microsoft ADO.NET Data Services"
$request.Accept = "application/atom+xml,application/xml"
$request.ContentType = "application/atom+xml"
$request.KeepAlive = $true

# If runbook servers are specified, format the string
$rbServerString = ""
if (-not [string]::IsNullOrEmpty($RunbookServers)) {
   $rbServerString = -join ("<d:RunbookServers>",$RunbookServers,"</d:RunbookServers>")

# Format the Runbook parameters, if any
$rbParamString = ""
if ($rbParameters -ne $null) {
   # Format the param string from the Parameters hashtable
   $rbParamString = "<d:Parameters><![CDATA[<Data>"
   foreach ($p in $rbParameters.GetEnumerator())
      #$rbParamString = -join ($rbParamString,"&lt;Parameter&gt;&lt;ID&gt;{",$p.key,"}&lt;/ID&gt;&lt;Value&gt;",$p.value,"&lt;/Value&gt;&lt;/Parameter&gt;")         
      $rbParamString = -join ($rbParamString,"<Parameter><ID>{",$p.key,"}</ID><Value>",$p.value,"</Value></Parameter>")
   $rbParamString += "</Data>]]></d:Parameters>"

# Build the request body
$requestBody = @"
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xmlns:d="" xmlns:m="" xmlns="">
    <content type="application/xml">
            <d:RunbookId m:type="Edm.Guid">$rbid</d:RunbookId>

# Create a request stream from the request
$requestStream = new-object System.IO.StreamWriter $Request.GetRequestStream()
# Sends the request to the service

# Get the response from the request
[System.Net.HttpWebResponse] $response = [System.Net.HttpWebResponse] $Request.GetResponse()

# Write the HttpWebResponse to String
$responseStream = $Response.GetResponseStream()
$readStream = new-object System.IO.StreamReader $responseStream
$responseString = $readStream.ReadToEnd()

# Close the streams

# Get the ID of the resulting job
if ($response.StatusCode -eq 'Created')
    $xmlDoc = [xml]$responseString
    $jobId = $
    Write-Host "Successfully started runbook. Job ID: " $jobId
    Write-Host "Could not start runbook. Status: " $response.StatusCode


Modify the value of the variable $rbid with the GUID of the Runbook without {}

$rbid = "1bf21126-839d-4698-9570-35696fa96dbs"


Modify the value of the variable $rbParameters with the GUID of the Runbook Parameters without {}

Warning: The letters in the IDs of the runbook parameters must be in lowercase or Orchestrator web service returns a 500 error!

$rbParameters = @{"bfd12058-0cfd-4d18-ae90-b347a70f4dbs" = "Content of the mail";"1d9b100a-f2e3-4114-bed9-79c382532dbs" = "";"50fd8101-3d4a-4dde-8482-b8f084d52dbs" = "";"aaf06613-c304-4b33-8ce8-0f27ad29bdbs" = "Subject of the email"}



3. Run the Script

Run the script using an account with access rights to Orchestrator: