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.
SYNTAX
ScoJobRunner -ID:<runbookID> [-Parameters:<job parameters>]
[-Webserver:<server>] [-Port:<port number>] [-RunbookServer:<server>]
[[-Username:<username>] [-Domain:<domain>] [-Password:<password>]]
[-Verbose]
ScoJobRunner -ID:<runbookID> -GetParameters [-Verbose]
PARAMETERS
-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'"
-GetParameters
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.
-Verbose
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?
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: http://orchestrator.codeplex.com/SourceControl/list/changesets