Starting a RunbookIn 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><Data><Parameter><ID>{60a8fa04-6293-4767-b842-46cba5790553}</ID><Value>Hello</Value></Parameter><Parameter><ID>{c24d1cc5-deba-4bb5-b02e-44caf0fb296c}</ID><Value>World</Value></Parameter></Data></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/"datetime'2012-02-20T02%3A48%3A55.98'"" 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><Data><Parameter><ID>{60a8fa04-6293-4767-b842-46cba5790553}</ID><Value>World</Value></Parameter><Parameter><ID>{c24d1cc5-deba-4bb5-b02e-44caf0fb296c}</ID><Value>Hello</Value></Parameter></Data></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/"datetime'2012-02-20T03%3A16%3A37.99'"" 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.
Microsoft