Runbook Instance
Applies To: System Center 2012 - Orchestrator, System Center 2012 R2 Orchestrator, System Center 2012 SP1 - Orchestrator
The Runbook Instance entity represents an instance created by an Orchestrator runbook. The Runbook Instances collection includes all of the runbook instances run by the local Orchestrator environment.
Properties
The following table lists the properties of the Job entity.
Name | Type | Key | |
---|---|---|---|
CreationTime |
DateTime |
No |
Date and time that the runbook instance was created. |
CompletionTime |
DateTime |
No |
The date and time that the runbook instance completed. |
Id |
GUID |
Yes |
Unique identifier of the runbook instance. |
JobId |
GUID |
No |
Unique identifier of the job that created the runbook instance. |
RunbookId |
GUID |
No |
Unique identifier of the runbook that started the runbook instance. |
RunbookServerId |
GUID |
No |
Unique identifier of the runbook server that the runbook instance ran on. |
Status |
String |
No |
Completion status of the runbook instance. |
Relationships
The following table lists the entities that share a relationship with the Job entity and the key property in each entity used to define the relationship.
Collection | Entity | Relationship | Related Entity Property | Runbook Instance Entity Property |
---|---|---|---|---|
ActivityInstances |
ActivityInstance |
Child |
RunbookInstanceId |
Id |
Jobs |
Job |
Parent |
Id |
JobId |
Parameters |
RunbookInstanceParameters |
Child |
RunbookInstanceId |
Id |
Runbooks |
Runbook |
Parent |
Id |
RunbookId |
RunbookServers |
RunbookServer |
Parent |
Id |
RunbookServerId |
Code Samples
Getting Runbook Instances using C#
The following code retrieves all instances of a particular runbook using C#. It uses a Data Services query in order to step through the different pages of runbook instances that are returned from the service. For more information, see Paging in Orchestrator Web Service.
This example uses a service reference named SCOService and uses the credentials of the current user context. You can uncomment the line that specifies alternate credentials if the current user does not have appropriate permissions to the runbook being started. For more information see Programming in Visual Studio With the Orchestrator Web Service and Authentication and Authorization.
namespace CodeSample.Microsoft.SystemCenter.Orchestration.WebService
{
using System;
using System.Collections;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Net;
using System.IO;
using System.Data.Services.Client;
using SCO.SCOService;
public class RunbookInstances
{
public static void Main()
{
Guid runbookId = new Guid("00000000-0000-0000-0000-000000000000");
// Path to Orchestrator web service
string serviceRoot = "http://server01.contoso.com:81/Orchestrator2012/Orchestrator.svc";
// Create Orchestrator context
SCOService.OrchestratorContext context = new SCOData.OrchestratorContext(new Uri(serviceRoot));
// Set credentials to default or to a specific user.
context.Credentials = System.Net.CredentialCache.DefaultCredentials;
//context.Credentials = new System.Net.NetworkCredential("user", "pwd", "domain");
// Setup Data Services query
DataServiceQueryContinuation<RunbookInstance> nextRunbookInstanceLink = null;
try
{
// Setup the query to retrieve the jobs
var runbookInstancesQuery = (from runbookInstance in context.RunbookInstances
where (runbookInstance.RunbookId == runbookId)
select runbookInstance) as DataServiceQuery<RunbookInstance>;
// Run the initial query
QueryOperationResponse<RunbookInstance> queryResponse = runbookInstancesQuery.Execute() as QueryOperationResponse<RunbookInstance>;
do
{
// Keep querying the next page of jobs until we reach the end
if (nextRunbookInstanceLink != null)
{
queryResponse = context.Execute(nextRunbookInstanceLink) as QueryOperationResponse<RunbookInstance>;
}
// Output the properties of each job on the current page to the console
foreach (RunbookInstance runbookInstance in queryResponse)
{
Console.WriteLine("JobId = {0}, Completion Time = {1}. Status = {2}",
runbookInstance.JobId,
runbookInstance.CompletionTime,
runbookInstance.Status);
}
} while ((nextRunbookInstanceLink = queryResponse.GetContinuation()) != null);
}
catch (DataServiceQueryException ex)
{
throw new ApplicationException("An error occurred during query execution.", ex);
}
}
}
}
Getting Runbook Instances using Windows PowerShell
The following code retrieves all instances of a particular runbook using Windows PowerShell. It pages through the result in case there are more than 50 entries in the result set. The example uses the credentials of the current user context. For more information, see Paging in Orchestrator Web Service. You can uncomment the line that specifies alternate credentials if the current user does not have appropriate permissions to the runbook being started. For more information see Authentication and Authorization.
# Details of the runbook we want to get
$runbookId = "00000000-0000-0000-0000-000000000000"
# Base URL for Instances collection
$baseUrl = -join ("http://server01.contoso.com:81/Orchestrator2012/Orchestrator.svc/","Runbooks(guid'",$runbookId.ToString(),"')/Instances")
# Assume maximum entries on a page to be 50
$page = 0
$pageSize = 50
do {
# Setup query options and add to end of base URL for request
$skip = $page * $pageSize
$queryOptions = "?`$skip=$skip&`$top=$pageSize&`$inlinecount=allpages"
$url = -join ($baseUrl,$queryOptions)
$request = [System.Net.HttpWebRequest]::Create($url)
# Set the credentials to default or prompt for credentials
$request.UseDefaultCredentials = $true
# $request.Credentials = Get-Credential
# Build the request header
$request.Method = "GET"
$request.UserAgent = "Microsoft ADO.NET Data Services"
# Get the response from the request
[System.Net.HttpWebResponse] $response = [System.Net.HttpWebResponse] $Request.GetResponse()
# Write the HttpWebResponse to String
$reader = [IO.StreamReader] $response.GetResponseStream()
$output = $reader.ReadToEnd()
[xml]$output = $output
$reader.Close()
# Setup namespaces for response
$ns = New-Object Xml.XmlNamespaceManager $output.NameTable
$ns.AddNamespace( "a", "http://www.w3.org/2005/Atom")
$ns.AddNamespace( "d", "https://schemas.microsoft.com/ado/2007/08/dataservices")
$ns.AddNamespace( "m", "https://schemas.microsoft.com/ado/2007/08/dataservices/metadata")
# Get total number of entries in results so we know how many pages we need to request
$totalCount = ($output.SelectSingleNode("//m:count",$ns)).InnerText
$page += 1
# Output properties of each job in page to host
foreach ($instance in $output.feed.entry)
{
Write-Host "JobId = " $instance.content.properties.JobId.InnerText
Write-Host "Completion Time = " $instance.content.properties.CompletionTime.InnerText
Write-Host "Status = " $instance.content.properties.Status
}
} until (($page*$pageSize) -ge $totalCount) # Continue until all instances have been displayed
See Also
Concepts
Programming Using the Orchestrator Web Service
OData Queries Using the Orchestrator Web Service
Authentication and Authorization
Paging in Orchestrator Web Service