Using PowerShell to run an Orchestrator Runbook by Name

I’ve seen a lot of posts on the Internet describing how you can use Orchestrator to trigger a Runbook when a condition is met. For example, Orchestrator can poll SCOM for a specific event and when it occurs it can trigger a Runbook . But what about when you want to trigger a Runbook from a different source? So today I took a look at how I could use PowerShell to trigger a Runbook. Now I have seen some posts describing how to extract the GUID of a Runbook and use that to start the Runbook. I’m not going to do that, I’m going to start a Runbook using only the name of the Runbook which I think is much easier for people to identify with a name, not a GUID. But hey, if you want to use the GUID, feel free to skip the rest of my post and head off to an example from Microsoft here:

So my environment I have a Runbook that I use to fix HeartBeat failures for SCOM so I’m going to use that one for my demo here. Now I’m not going to try an reinvent the wheel, I’m going to use some code that’s already been supplied to us from Microsoft. Head off to Codeplex and download this file:

In this zip you’ll find a file called OrchestratorServiceModule. I’m going to modify that for use in my script (which I’ll supply at the end of this article). So credit goes to Microsoft for supplying the bulk of this script, I’m just going to add in a few things to make it work the way I want.

The first thing I want to do is define a few things in the script… specifically I want to tell the script the name of my Orchestrator Server, the target for my Runbook and the Name of the Runbook that I wish to execute. You’ll probably want to pass in these as parameters to your script like this:


So when we execute our PowerShell script, we’ll call it like this…

.\Start-Runbook.ps1 -RunbookName “Name of your Runbook” -WebServer “Name of your Orchestrator Server” -InParameter “Server Name = TargetServer.Domain.Com”


The InParameter Parameter is optional and used to define a target server to run this Runbook against (we’ll use it in the next blog post where we kick off a Runbook to fix a SCOM Heartbeat Failure).

Finally at the bottom of the script, we’ll add in a bit of code to find the Runbook and then run it against our target (or simply just run it, if we didn’t provide an InParameter Parameter).


if ( $InParameter )

# Create a Hash Table
$GUIDParams = @{}

foreach ($SCOParam in $RunbookParams)
if ($InParam.ContainsKey($SCOParam.Name))
write-host “-I- Supplied hash contains a key. The value is $($InParam.Get_item($($SCOParam.Name)))”
# Add to new hash
write-host “-E- Supplied hash is missing a parameter”
exit 8

# Now we’ll Start the Runbook against a Target Server.
Start-OrchestratorRunbook -Runbook $Runbook -Parameters $GUIDParams

# Now we’ll Start the Runbook using just the name of the Runbook.
Start-OrchestratorRunbook -Runbook $Runbook



If everything goes well, you’ll get output like this:






And you’ll see your Orchestrator Runbook fire up and start automating!

The script can be downloaded here: Start-Runbook

In the upcoming 3rd part in this instalment, I’ll show you how we can use this code in a SCOM Recovery to have an alert trigger this runbook so that when we get a HeartBeat failure, this Runbook will be triggered FROM SCOM, not from Orchestrator.



You have done a great job with this script mate and it fires off single input runbooks perfectly.

Have you come across the need to have two input parameters being passed to a runbook?

Trackbacks for this post

Leave a Reply