Starting a Runbook

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

POST http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs HTTP/1.1

User-Agent: PowerShell API Client (PowerShell 2.0; .NET CLR 2.0.50727.5448; WinNT 6.1.7601 Service Pack 1)
Accept: application/atom+xml,application/xml
Content-Type: application/atom+xml
Accept-Encoding: identity
Accept-Language: en-US
DataServiceVersion: 1.0;NetFx
MaxDataServiceVersion: 2.0;NetFx
Pragma: no-cache
Host: SERVER:81
Content-Length: 779
Expect: 100-continue

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices"
xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata"
xmlns="http://www.w3.org/2005/Atom">
<content type="application/xml">
<m:properties>
<d:RunbookId m:type="Edm.Guid">0336c79b-ca82-449e-ad55-aefa9fb47fad</d:RunbookId>
<d:Parameters>&lt;Data&gt;&lt;Parameter&gt;&lt;ID&gt;{60a8fa04-6293-4767-b842-46cba5790553}&lt;/ID&gt;&lt;Value&gt;Hello&lt;/Value&gt;&lt;/Parameter&gt;&lt;Parameter&gt;&lt;ID&gt;{c24d1cc5-deba-4bb5-b02e-44caf0fb296c}&lt;/ID&gt;&lt;Value&gt;World&lt;/Value&gt;&lt;/Parameter&gt;&lt;/Data&gt;</d:Parameters>
</m:properties>
</content>
</entry>

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.


Figure 2. HTTP Response from the Request to Start a Job
HTTP/1.1 201 Created
Cache-Control: no-cache
Content-Length: 2945
Content-Type: application/atom+xml;charset=utf-8
ETag: W/"datetime'2012-02-20T02%3A48%3A55.98'"
Location: http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')
Server: Microsoft-IIS/7.5
X-AspNet-Version: 4.0.30319
DataServiceVersion: 1.0;
Persistent-Auth: true
X-Powered-By: ASP.NET
Date: Mon, 20 Feb 2012 02:48:55 GMT

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://SERVER:81/Orchestrator2012/Orchestrator.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/&quot;datetime'2012-02-20T02%3A48%3A55.98'&quot;" xmlns="http://www.w3.org/2005/Atom">
<id>http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')</id>
<title type="text"></title>
<published>2012-02-20T02:48:55-08:00</published>
<updated>2012-02-20T02:48:55-08:00</updated>
<author>
<name />
</author>
<link rel="edit" title="Job" href="Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Runbook" type="application/atom+xml;type=entry" title="Runbook" href="Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')/Runbook" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Instances" type="application/atom+xml;type=feed" title="Instances" href="Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')/Instances" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/RunbookServer" type="application/atom+xml;type=entry" title="RunbookServer" href="Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')/RunbookServer" />
<link rel="http://schemas.microsoft.com/ado/2007/08/dataservices/related/Statistics" type="application/atom+xml;type=feed" title="Statistics" href="Jobs(guid'42fe8a86-bdea-47c9-aecb-845fdba8f8ca')/Statistics" />
<category term="Microsoft.SystemCenter.Orchestrator.WebService.Job" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:Id m:type="Edm.Guid">42fe8a86-bdea-47c9-aecb-845fdba8f8ca</d:Id>
<d:RunbookId m:type="Edm.Guid">0336c79b-ca82-449e-ad55-aefa9fb47fad</d:RunbookId>
<d:Parameters>&lt;Data&gt;&lt;Parameter&gt;&lt;ID&gt;{60a8fa04-6293-4767-b842-46cba5790553}&lt;/ID&gt;&lt;Value&gt;World&lt;/Value&gt;&lt;/Parameter&gt;&lt;Parameter&gt;&lt;ID&gt;{c24d1cc5-deba-4bb5-b02e-44caf0fb296c}&lt;/ID&gt;&lt;Value&gt;Hello&lt;/Value&gt;&lt;/Parameter&gt;&lt;/Data&gt;</d:Parameters>
<d:RunbookServers m:null="true" />
<d:RunbookServerId m:type="Edm.Guid" m:null="true" />
<d:ParentId m:type="Edm.Guid" m:null="true" />
<d:ParentIsWaiting m:type="Edm.Boolean">false</d:ParentIsWaiting>
<d:Status>Pending</d:Status>
<d:CreatedBy>S-1-5-21-3461259963-3254288209-657424328-1106</d:CreatedBy>
<d:CreationTime m:type="Edm.DateTime">2012-02-20T02:48:55.98</d:CreationTime>
<d:LastModifiedBy>S-1-5-21-3461259963-3254288209-657424328-1106</d:LastModifiedBy>
<d:LastModifiedTime m:type="Edm.DateTime">2012-02-20T02:48:55.98</d:LastModifiedTime>
</m:properties>
</content>
</entry>

 

Stopping a Job

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.


Figure 3. HTTP Request to Stop a Job
POST http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs(guid'01990fbd-19a4-42bd-82c2-9d37dc8dbc33') HTTP/1.1

User-Agent: PowerShell API Client (PowerShell 2.0; .NET CLR 2.0.50727.5448; WinNT 6.1.7601 Service Pack 1)
Accept: application/atom+xml,application/xml
Content-Type: application/atom+xml
Accept-Encoding: identity
Accept-Language: en-US
DataServiceVersion: 1.0;NetFx
MaxDataServiceVersion: 2.0;NetFx
Pragma: no-cache
X-HTTP-Method: MERGE
If-Match: W/"datetime'2012-02-20T03%3A16%3A37.99'"
Host: SERVER:81
Content-Length: 1568
Expect: 100-continue

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<entry xml:base="http://SERVER:81/Orchestrator2012/Orchestrator.svc/" xmlns:d="http://schemas.microsoft.com/ado/2007/08/dataservices" xmlns:m="http://schemas.microsoft.com/ado/2007/08/dataservices/metadata" m:etag="W/&quot;datetime'2012-02-20T03%3A16%3A37.99'&quot;" xmlns="http://www.w3.org/2005/Atom">
<id>http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs(guid'01990fbd-19a4-42bd-82c2-9d37dc8dbc33')</id>
<title type="text"></title>
<published>2012-02-20T03:16:36.313Z</published>
<updated>2012-02-20T03:16:37.99Z</updated>
<author><name /></author>
<category term="Microsoft.SystemCenter.Orchestrator.WebService.Job" scheme="http://schemas.microsoft.com/ado/2007/08/dataservices/scheme" />
<content type="application/xml">
<m:properties>
<d:Id m:type="Edm.Guid">01990fbd-19a4-42bd-82c2-9d37dc8dbc33</d:Id>
<d:RunbookId m:type="Edm.Guid">37abf178-38f6-4f21-bc15-c51ba45523af</d:RunbookId>
<d:Parameters m:null="true" />
<d:RunbookServers m:null="true" />
<d:RunbookServerId m:type="Edm.Guid">b83b8f14-c011-48c5-9661-563e1a335952</d:RunbookServerId>
<d:ParentId m:type="Edm.Guid" m:null="true" />
<d:ParentIsWaiting m:type="Edm.Boolean">false</d:ParentIsWaiting>
<d:Status>Canceled</d:Status>
<d:CreatedBy>S-1-5-21-3461259963-3254288209-657424328-1106</d:CreatedBy>
<d:CreationTime m:type="Edm.DateTime">2012-02-20T03:16:36.313</d:CreationTime>
<d:LastModifiedBy>S-1-5-500</d:LastModifiedBy>
<d:LastModifiedTime m:type="Edm.DateTime">2012-02-20T03:16:37.99</d:LastModifiedTime>
</m:properties>
</content>
</entry>

 

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.


Figure 4. HTTP Response from the request to stop a job
HTTP/1.1 204 No Content
Cache-Control: no-cache
Content-Length: 0
ETag: W/"datetime'2012-02-20T03%3A18%3A47.437'"
Server: Microsoft-IIS/7.5
X-AspNet-Version: 4.0.30319
DataServiceVersion: 1.0;
Persistent-Auth: true
X-Powered-By: ASP.NET
Date: Mon, 20 Feb 2012 03:18:46 GMT

Sample PowerShell Module

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:

  • Start a runbook
  • Start a runbook and get the results
  • Stop a job
  • Stop all jobs on a runbook server

You can download the module and test files from http://orchestrator.codeplex.com/releases/view/82959.

Conclusion

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.