In Orchestrator a runbook is started by inserting a record in the jobs table in the database. The record contains at minimum the Runbook ID and any input parameters required by the runbook. Optionally, the record may indicate the Runbook server(s) to use for the job. Runbook servers are frequently polling the database for jobs that need to be run, and when one is found the runbook server gets the runbook and executes it. The executing runbook is referred to as a runbook instance.
To start a runbook using the Orchestrator web service you create a HTTP POST request to the Jobs resource. In the request header you set several parameters, and in the request body you indicate the runbook id and any parameters. Figure 1 illustrates a HTTP request to start a runbook.
Figure 1. HTTP Request to Start a Runbook
When the Orchestrator web service gets this request it creates a job record in the database and then returns the job information, including the job id, in the HTTP response. Figure 2 illustrates the response from the request in Figure 1.
In Orchestrator a job is stopped by updating the job record in the database and setting the job status to "Canceled".
To stop a job using the Orchestrator web service you create a HTTP POST request to the particular Job resource (Figure 3). In the request header you must set several fields including the custom fields X-HTTP-Method and If-Match (http://msdn.microsoft.com/en-us/library/dd541168(v=prot.10).aspx). X-HTTP-Method: MERGE is a custom header used with the POST method that informs the service to process the request as a MERGE. If-Match is used to place a condition on the request action, in this case to assure that the job record being updated in the database still has the same LastModifiedTime as the LastModifiedTime in the request.
When the Orchestrator web service gets this request it updates the job record in the database (if the If-Match condition is satisfied) and then returns the status. The request is successful if the response status is "No Content". Figure 4 illustrates the response from the request in Figure 3.
To illustrate the use of PowerShell to start runbooks and stop jobs using the Orchestrator web service I created a PowerShell module with functions that enable all of the examples in this post and more. Scenarios illustrated include these:
You can download the module and test files from http://orchestrator.codeplex.com/releases/view/82959.
The Orchestrator web service allows remote control over the execution of runbooks. In this post, I illustrated the key concepts for starting runbooks and stopping jobs using HTTP POST requests. In a related post, I show how to retrieve Orchestrator resource data using PowerShell and the web service.