Cool Tool: New Command Line Utility to Start a Runbook

Cool Tool: New Command Line Utility to Start a Runbook

  • Comments 12
  • Likes

I was talking with one of the other Program Managers on the team the other day about how he wanted to be able to launch a runbook as part of a remediation task in Operations Manager, and how it would be great if he has some command-line utility that would enable him to do that quickly via a simple command. I had also been thinking something along those lines in terms of using the Windows Task Scheduler to periodically launch runbooks as a way to avoid the complexity of the scheduling activities in Orchestrator. Of course, the topic has come up time and time again in the discussion lists, and while we’ve talked about using the web service or PowerShell to the web service, those processes still weren’t that simple.

So this morning I decided to sit down and put together a simple command-line utility that would use the web service to start new runbook jobs, but enable it in a way that was easy to script or put into command lines used by other tools.  A couple of hours later, in between all the emails and meeting requests I typically receive, I had a prototype done. After a few more hours of tweaking, improving, and sifting through more email and meeting requests, I had something I could actually release to everyone as a sample to play around with.

The tool, affectionately called the SCO Job Runner (I know…why spend millions of dollars on market research?), has two primary functions. One, it runs new Orchestrator runbook jobs (who would have guessed, right?). Second, it lets you get the parameters of a runbook, already formatted in the way the utility expects to receive them on the command line.

But wait! There’s more! You can run this utility from anywhere as long as you have access to the Orchestrator Web Service (you can specify the web server and port). You can use alternate credentials if you like. You can even tell it what Runbook Server to run the job on! I know! It’s amazing!

When you run the utility without any parameters, you get the usage:

SCOJobRunner - a command line tool to invoke runbooks for Orchestrator 2012.

ScoJobRunner -ID:<runbookID> [-Parameters:<job parameters>]
[-Webserver:<server>] [-Port:<port number>] [-RunbookServer:<server>]
[[-Username:<username>] [-Domain:<domain>] [-Password:<password>]]

ScoJobRunner -ID:<runbookID> -GetParameters [-Verbose]


  -ID <string>
     The runbook ID to be invoked in the format of a GUID
     (i.e. "2d2fd2b4-339a-47ad-9914-a217d9fd47a6").

  -Parameters <string>
     A list of name-value pairs of the parameters needed by the runbook.
     The format of these parameters is: "Name=Value;Name=Value"
     Enclose in quotes to correctly handle spaces.
     Example:  -Parameters "Path='Path 1';Other Text='sample data here'"

     When this parameter is added, the utility returns a list of the runbook
     parameters formatted in a way you can use them on the command line.
     Example return value: "Path='Path 1';Other Text='sample data here'"

  -Webserver <string>
     The name of the Orchestrator server where the web service is installed.
     If not provided, defaults to the current computer.

  -Port <int>
     The port number used by the web service. If not provided, defaults to 81.

  -RunbookServer <string>
     The Runbook Server where the job should be run.
     If not provided, defaults to the configured primary Runbook Server.

  -Username <string> -Domain <string> -Password <string>
     If provided, allows the use of alternate credentials for invoking the
     runbook. All three parameters must be specified if used.
     If not provided, the current user credentials are used.

     If this parameter is included, provides additional console output during
     the processing of the job creation process.

Using the utility is simple. First, I want to get the parameters for the runbook I want to run to make sure I fill them out correctly. To do that I just enter this:

SCOJobRunner -ID:"2d2fd2b4-339a-47ad-9914-a217d9fd47a6" -GetParameters

Then, to run the job, I take the string that was returned:

"Path='value';Other Text='value'"

…and then use it in a new command line, modifying the “value” parts with real parameter values. For instance:

SCOJobRunner -ID:"2d2fd2b4-339a-47ad-9914-a217d9fd47a6" –Parameters:"Path='Path 1';Other Text='some other text here'"

Note: Be sure to enclose parameter values that include spaces with single quotes so they’ll all be treated as one value.

That’s it! That’s all I need to run a job from the command line. Of course if I want to run the command from my desktop but the web service is on another computer, I can just reformat the command like this:

SCOJobRunner -ID:"2d2fd2b4-339a-47ad-9914-a217d9fd47a6" -WebServer:"scoserver" -User:administrator -Domain:mydomain -Password:myPassword -Parameters:"Path='Path 1';Other Text='some other text here'"

Now I have the ability to start a job from anywhere as long as I know the runbook ID and the computer where the web services are installed. Ok, I know, using a runbook ID isn’t exactly the most pleasant way to specify what to run. However, it does provide a very distinct way to determine which runbook will run. Just how many “New Runbook” runbooks are in your system anyway? Smile

I will have a future blog about the different ways that you can use this utility, including Task Scheduler, Operations Manager, Configuration Manager, and more. Until then, go download and play with the utility and send some feedback on what you think!

Download the zip file containing the utility here:  SCO Job Runner - Command Line Utility

Download the source code to the utility here:

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • Very cool stuff Robert :-), I still think you should be able to launch or look up by runbook path (just as unique as runbook id but much more 'apparent' to runbook designers) though :-)

  • Hi Ryan,

    That other command line tool supports launching runbooks by path, and also pattern checking for parameters values. It also talks to the web service.

    Hope this helps!

  • Bruno...did I completely forget about an existing tool of yours? D'oh!

  • The article that is posted by you is usually really, and that I like better to browse quality content, therefore I’m happy to search out such a big amount of smart points here in writing, thanks substantially for the blog that you simply have posted here.

  • I can initiate a runbook via webservices, but what if I want to check it's status so I know when the job is completed? I'm working off the MS example of how to start a runbook with C#

  • Hi Robert,

    SCOJobRunner + task scheduler issue, every task execution:

    Application: SCOJobRunner.exe

    Framework Version: v4.0.30319

    Faulting application name: SCOJobRunner.exe, version:, time stamp: 0x4fb2f87c

    Faulting module name: KERNELBASE.dll, version: 6.1.7601.17651, time stamp: 0x4e211319

    Exception code: 0xe0434352

    Fault offset: 0x0000b9bc

    Faulting process id: 0x14fc

    Faulting application start time: 0x01cd5fa22b865d97

    Faulting application path: E:\Tools\SCOJobRunner.exe

    Faulting module path: C:\Windows\syswow64\KERNELBASE.dll

    Report Id: 6beb2b0b-cb95-11e1-a1b3-00155d14137b

    Any ideas ?



  • Quick question:  How do you get the ID of a runbook?

  • Thanks Robert, this is very useful tool.

    Do we have any alternative ways to schedule runbooks? If you could you please help in stating them out.

  • I found a need to mod your code. Specifically this: string[] pair = parameterSet.Split('='); To this: string[] pair = parameterSet.Split(new char[] {'='}, 2); I'm passing in a string value that contains '=' symbols (AD Search Root) so needed to use the overload to only split on the first '=' symbol for each pair. Regards.

  • Have similar problems... i assume, its since a .net patch or update...
    any ideas?


    Faulting application name: SCOJobRunner.exe, version:, time stamp: 0x4fb2f87c
    Faulting module name: KERNELBASE.dll, version: 6.1.7601.18229, time stamp: 0x51fb1116
    Exception code: 0xe0434352
    Fault offset: 0x0000c41f
    Faulting process id: 0x41cc
    Faulting application start time: 0x01cf4f59f537dc29
    Faulting application path: C:\SCOJobRunner\SCOJobRunner.exe
    Faulting module path: C:\Windows\syswow64\KERNELBASE.dll
    Report Id: 340931fa-bb4d-11e3-aa23-0050568b0e02

    Application: SCOJobRunner.exe
    Framework Version: v4.0.30319
    Description: The process was terminated due to an unhandled exception.
    Exception Info: System.Data.Services.Client.DataServiceRequestException
    at System.Data.Services.Client.DataServiceContext+SaveResult.HandleBatchResponse()
    at System.Data.Services.Client.DataServiceContext+SaveResult.EndRequest()
    at System.Data.Services.Client.DataServiceContext.SaveChanges(System.Data.Services.Client.SaveChangesOptions)
    at System.Data.Services.Client.DataServiceContext.SaveChanges()
    at Microsoft.SystemCenter.Orchestrator.Integration.Administration.SCOJobRunner.SCOJobRunner.InvokeRunbook()
    at Microsoft.SystemCenter.Orchestrator.Integration.Administration.SCOJobRunner.SCOJobRunner.Main(System.String[])

  • Why doesn't the -RunbookServer parameter work? My job keeps defaulting to the primary runbook server even though I specify an override using the parameter.

  • Fixed a bug with the way the runbookserver is set.