Starting Runbooks and Stopping Jobs Using the System Center 2012 Orchestrator Web Service

[System-Center-Team]

First published on TECHNET on Mar 25, 2012

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>&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.