Initiating Runbooks from Task Scheduler


A question came up in the Orchestrator Forums the other day ( about how to schedule the execution of a Runbook.  A number of good suggestions were given and ultimately using task scheduler was given as a potential solution.  The question then becomes, how do we go about doing that?  The answer is through Orchestrator’s web service which is documented at  Great, so we have a reference document that a programmer could take and use to interact with the web service but all we want to do is initiate a Runbook, so what do we do?  The good news is that there are already solutions out there to make this interaction quite a bit easier (both examples I use will end up being a simple PowerShell script you can call from Task Scheduler.  The two solutions I am aware of are a PowerShell script module available from Chris Sanders at Microsoft — – and a c# interop class utilized by the Orchestrator Web Service Integration Pack from the community SCORCH project available at

PowerShell Module Answer

Playing around with the PowerShell Module

If  you would like to interact with the PowerShell module the first step (after downloading) is to load it into a PowerShell instance


You now have access to all of the functions inside the PowerShell module in this instance and there are quite a few of them.  The two we are interested in for initiating a Runbook are Get-OrchestratorRunbook and Start-OrchestratorRunbook.  At its base it would like two parameters passed to it, the SeriveURL to your Orchestrator web service and the Runbook GUID you would like to initiate

Orchestrator Web Service URL

This is the URL of your web service.  By default it will be of the form http://webservername:81/Orchestrator2012/Orchestrator.svc/ – Note that for the powershell module to work correctly you MUST have the final / on the URL

Runbook GUID

This is the GUID of the Runbook you would like to initiate.  This can be found in a number of ways including browsing to the web service using a browser, looking up your Runbook and grabbing the GUID.  Note, you can use filters in your URL to help you browse to the correct Runbook.  For example, http://webservername:81/Orchestrator2012/Orchestrator.svc/Runbooks?$filter=Name eq ‘Tier 1: Webservice Entry’ will return all Runbooks with the name ‘Tier 1: Webservice Entry’.  Once I have found the one I want I grab its Guid and I can go back to PowerShell


PowerShell Initiation

Step1: Setup a variable to house your web service URL

Step2: Run get-OrchestratorRunbook



Step3: Run Start-OrchestratorRunbook

Now that we have the Runbook referenced in the $runbook variable we can use Start-OrchestratorRunbook cmdlet to initiate it!  If your Runbook requires input parameters you need to put them into a hashtable.

$parameters = @{“User Email Address” = “”}


The PowerShell Script to Use for Scheduling

Putting it all together you could use the following script for initiating a Runbook with a few modifications

$ServiceURL = “http://webservername:81/Orchestrator2012/Orchestrator.svc/”
$RunbookGUID = “571e7c58-2d26-4f9b-a3c3-857f8fb9eb7a”

$runbook = Get-OrchestratorRunbook -ServiceUrl $ServiceURL -RunbookId $RunbookGUID
$parameters = @{“Param 1”, “Param Value”}

Start-OrchestratorRunbook -Runbook $runbook -Parameters $parameters

C# Interop Class Answer

Why an Interop Class

It is generic.  It can be used by developers as a reference class or inside of a PowerShell script.  It was initially developed to facilitate the functions exposed in the Orchestrator Web Service Integration Pack

How do you load it in PowerShell?

Loading a .DLL file inside of PowerShell is a lot like loading a PowerShell module class. The difference is that instead of using Import-Module you use [reflection.assembly]::LoadFile



How do we initiate a Runbook with it?

Just like the PowerShell module, the first thing you need to do is provide a URL pointing to your web service

$OrchServiceUrl = New-Object system.uri(

Then you setup an environment connection

$sco = New-Object OrchestratorInterop.SCOrchestrator.OrchestratorContext($OrchServiceUrl)

$sco.Credentials = [System.Net.CredentialCache]::DefaultCredentials
$sco.MergeOption = [System.Data.Services.Client.MergeOption]::OverwriteChanges

Then setup any needed input parameters

$inputParameters = new-object ‘system.collections.generic.dictionary[string, string]’
$inputParameters.Add(‘User Email Address’,’’)

You then have a choice, how would you like to reference the Runbook, by path or by Guid (like the PowerShell Module), for this example I will initiate by Path

$runbookPath = ‘\Prod\Exchange\OutOfOffice\Tier 1: Webservice Entry’

This runbook is inside the “Prod –> Exchange –> OutOfOffice” folder and called Tier1: Webservice Entry

Then you can initiate the Runbook using



The cool part is you could also go one step further and wait for the job to complete and grab any output parameters (if you wanted)

$jobDetails = [OrchestratorInterop.SCOrch]::getJobDetails($sco,$jobID)

while(-not ($jobDetails.Job.Status.Equals(“Completed”)))
$jobDetails = [OrchestratorInterop.SCOrch]::getJobDetails($sco,$jobID)



The PowerShell Script

So putting it all together a PowerShell script using this interface for Launching a Runbook would look like

$OrchServiceUrl = New-Object system.uri(“”)
$sco = New-Object OrchestratorInterop.SCOrchestrator.OrchestratorContext($OrchServiceUrl)

$sco.Credentials = [System.Net.CredentialCache]::DefaultCredentials
$sco.MergeOption = [System.Data.Services.Client.MergeOption]::OverwriteChanges

$inputParameters = new-object ‘system.collections.generic.dictionary[string, string]’
$inputParameters.Add(‘User Email Address’,’’)

$runbookPath = ‘\Prod\Exchange\OutOfOffice\Tier 1: Webservice Entry’

$jobId = [OrchestratorInterop.SCOrch]::startRunbookJob($sco,$runbookPath,$inputParameters)


For more information on how to use the interop class please don’t hesitate to ask or look at the source code

Using Either PowerShell Script with Task Scheduler

Now that you have a PowerShell script it is as easy as using Task Scheduler to say when to initiate it.  The ‘Program’ is PowerShell itself (C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe), the arguments are –noninteractive -nologo d:\runRunbook.ps1


Tagged with: , ,
Posted in General Information
One comment on “Initiating Runbooks from Task Scheduler
  1. […] in orchestrator is unfriendly at best, and downright hostile in some cases. I know of at least two methods for scheduling runbooks outside of orchestrator, and I have a few coworkers who only use […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: