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