Accessing System Center 2012 Orchestrator Using the Web Service

Accessing System Center 2012 Orchestrator Using the Web Service

  • Comments 2
  • Likes

ReplicationTo enhance datacenter automation options, Orchestrator 2012 exposes a REST OData web service. The web service enables programmatic access to Orchestrator runtime resources like Runbooks, Jobs, and Events, and also enables a user to start Runbooks and stop Jobs.

One goal of the web service it to enable easy automation of the Orchestrator runtime from any application. To this end, the Orchestration console that is part of Orchestrator 2012 uses the web service to connect with Orchestrator.

OData

OData is a web protocol designed for clients to query and update data on data services. OData is REST-based, that is it uses standard HTTP syntax and methods (e.g., GET, POST) to enable CRUD operations on data. Data queries are defined with standard URL syntax, and response data is transferred in standard AtomPub or JSON formats.

Orchestrator OData

An OData service represents data as resources and relationships between resources. For Orchestrator, the resources exposed are those listed in Figure 1 below. For a given resource the relationships to other resources are also exposed; this means that a resource like a Runbook will have metadata (URLs) that represent the relationships to other resources like Jobs and Activities (see Figure 3 for examples).

Querying the Orchestrator Resource Collections

The base URL to the Orchestrator web service is this:

  • http://SERVER:81/Orchestrator2012/Orchestrator.svc/

In response to this HTTP GET request the web service will return by default AtomPub-format XML that contains the references to all of the Orchestrator resources exposed by the service (Figure 1).

Figure 1: The Orchestrator resource collections (AtomPub format)
Blog1Fig1

NOTE: With Internet Explorer, to view the web service response as XML rather than as a feed do the following:

  • Navigate to Options > Content > Feeds and Web Slices > Settings, and un-check “Turn on feed reading view”.

Connecting to the Orchestrator Web Service with PowerShell

One of the key uses of the Orchestrator web service is for automation via PowerShell scripts. Connecting with the web service is straightforward. Here is bare-bones script (Figure 2) that connects with the web service and retrieves the list of collections seen above (Figure 1):

Figure 2. PowerShell script for connecting with the Orchestrator web service and getting response xml

Blog1Fig2

Retrieving a Specific Resource Collection

To get the records for a specific resource the URL has this form:

  • http://SERVER:81/Orchestrator2012/Orchestrator.svc/COLLECTION-HREF/

where, COLLECTION-HREF can be found in the Collections xml (Figure 1) like this:

  • <collection href="Runbooks">

Thus, to retrieve the runbook resources use this URL:

  • http://SERVER:81/Orchestrator2012/Orchestrator.svc/Runbooks/

 

Figure 3: Runbook resources returned by the web service (AtomPub format)
Blog1Fig3

Each <entry> node contains the information for one resource. Using PowerShell it is straightforward to parse this xml into custom objects that can be easily used by other script.

Paging

For performance reasons the Orchestrator web service has a limit on the number of resources returned per page - at installation that limit is configured to 50 resources per page. To learn the total count of a particular resource and to get the resources page by page use the following construct in the query of the URL:

  • $skip=0&$top=50&$inlinecount=allpages
    • $skip is the number of records to skip
    • $top is the number of records to return (max of 50 unless reconfigured)
    • $inlinecount=allpages instructs the web service to include a count of all records

For example,

  • http://SERVER:81/Orchestrator2012/Orchestrator.svc/Jobs()?$skip=100&$top=50&$inlinecount=allpages
  • Will return the third page of the Jobs resource (with 50 records)
  • And the count appears in the response xml like this:
    • <m:count>153</m:count>
    • Indicating that there are a total of 153 jobs (which will require 4 pages to retrieve all of them)

Sample PowerShell Module

To illustrate the use of PowerShell to get resources from 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:

  • Get the collections exposed by the web service
  • Get a runbook
  • Get all runbooks in the system
  • Get a job
  • Get all jobs in the system
  • Get all jobs on a particular runbook server
  • Get all jobs with a particular status
  • Get all jobs for a particular runbook
  • Get all runbook instances for a particular job

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

Writing Your Own PowerShell

The functionality discussed in this post and implemented in the module are only a sample of what can be done. For example, there is a whole range of resource filtering that is possible. A good way to learn how to communicate via REST with the web service is to open the Orchestration console, start Fiddler, and see how various actions in the console are communicated between the console and the web service.

Conclusion

The Orchestrator web service exposes all of the key runtime resources. In this post, I have illustrated the key concepts for getting these resources using HTTP GET. In a related post, I show how to start runbooks and stop jobs using HTTP POST; these are actions that provide another level of programmatic interaction with Orchestrator.

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • It is really nice and informative, it is useful for me. thank you

  • Hello,

    Is it at all possible to do a HTTP GET to initiate an Orchestrator runbook?  ie;

    http://orchestrator:81/Orchestrator2012/Orchestrator.svc/Runbooks(guid'037dbb9a-0f7d-4286-8485-b83ecd811e76')/ComputerName=test

    For this example my only parameter is called "ComputerName".

    We have a PERL program that we want to simply add a web service call to initiate the runbook via orchestrator using HTTP GET. Assuming this is my RUNBOOK ID in the example how would I do that. I've scoured the web and haven't found anyone doing what I'm looking for.  I dont' want to have to leverage any other scripting language or program...just want to hit the URL with the parameter set and initiate the runbook. I hope I'm clear with this, and I truly appreciate your help,thanks;