Getting Deeper Information from Orchestrator via COM

[System-Center-Team]

First published on TECHNET on Apr 30, 2012
I see a lot of requests from people creating integrations with Orchestrator to get information about some of the inner workings of an installation, beyond what’s available via the web service. The web service allows you to retrieve information about:

• Folders
• Runbooks
• Runbook Parameters
• Activities
• Jobs
• Runbook Instances
• Runbook Instance Parameters
• Activity Instances
• Activity Instance Data
• Runbook Servers
• Runbook Diagrams
• Statistics
• Events

With the exception of starting and stopping jobs, everything through the web service is read only. However, people also want to be able to get at programmatically (and modify) things, and perform actions like:

• See and modify Variables and Counters
• See what Integration Packs are installed
• View Log History
• Import or Export runbooks
• Check in or checkout (or undo checkout of) a runbook
• See who has Runbook Designers connected to the Management Server

Well all of this and more is available through the Orchestrator COM interface. I’m going to use a few articles to explain how to connect to and use the COM interface for some various actions that will help you further automate your interactions with Orchestrator. I’ll use PowerShell for these examples because it’s easier than writing and compiling C# code (and certainly easier for me than C++).

First of all, I open a PowerShell (x86) ISE (since Orchestrator 2012 is not 64-bit). Note that for this example, you’ll need to do this on the Orchestrator Management Server.

I’m going to create a new object in PowerShell using the following command:

$oismgr = new-object -com OpalisManagementService.OpalisManager

From here, I can look inside the COM object and see a list of all the methods that are available (there are a lot of them!):

$oismgr | gm


TypeName: System.__ComObject#{9b7ffff7-3ac0-40ce-b2ae-99514a43307e}

Name                                    MemberType Definition
----                                    ---------- ----------
AccessCheck                             Method     void AccessCheck (int, string, int, string, Variant)
AddFolder                               Method     void AddFolder (int, string, Variant)
AddIntegrationPack                      Method     void AddIntegrationPack (int, Variant)
AddPolicy                               Method     void AddPolicy (int, string, Variant)
AddResource                             Method     void AddResource (int, string, Variant)
AddUserToRuntimeRole                    Method     void AddUserToRuntimeRole (int, string)
ChangeLicense                           Method     void ChangeLicense (string, string)
CheckIn                                 Method     void CheckIn (int, string, string, string)
CheckOut                                Method     void CheckOut (int, string, string, Variant)
ClientConnectSignal                     Method     void ClientConnectSignal (Variant)
ConfigureActionServer                   Method     void ConfigureActionServer (int, string, Variant)
Connect                                 Method     void Connect (string, string, Variant)
CreatePolicyRequest                     Method     void CreatePolicyRequest (int, string, int, string, string, string, string, Variant, Variant)
DeleteEvent                             Method     void DeleteEvent (int, string)
DeleteFolder                            Method     void DeleteFolder (int, string, int)
DeleteLogEntry                          Method     void DeleteLogEntry (int, string, string)
DeleteObject                            Method     void DeleteObject (int, string, string, int)
DeletePolicy                            Method     void DeletePolicy (int, string, int)
DeletePolicyImages                      Method     void DeletePolicyImages (Variant)
DeleteResource                          Method     void DeleteResource (int, string, string)
Disconnect                              Method     void Disconnect (int, string)
DoesPolicyExist                         Method     void DoesPolicyExist (string)
Find                                    Method     void Find (int, string, int, string, string, Variant)
FindPoliciesWithoutImages               Method     void FindPoliciesWithoutImages (int, Variant)
GetActionServers                        Method     void GetActionServers (int, string, Variant)
GetActionServerTypes                    Method     void GetActionServerTypes (int, Variant)
GetAuditHistory                         Method     void GetAuditHistory (int, string, string, string, Variant)
GetCheckOutStatus                       Method     void GetCheckOutStatus (int, string, Variant)
GetClientConnections                    Method     void GetClientConnections (int, Variant)
GetConfigurationIds                     Method     void GetConfigurationIds (int, Variant)
GetConfigurationValues                  Method     void GetConfigurationValues (int, string, Variant)
GetCountersValueAndMarker               Method     void GetCountersValueAndMarker (Variant)
GetCustomStartParameterName             Method     void GetCustomStartParameterName (string, Variant)
GetCustomStartParameters                Method     void GetCustomStartParameters (Variant)
GetDatastoreType                        Method     void GetDatastoreType (int)
GetEventDetails                         Method     void GetEventDetails (string, Variant)
GetEvents                               Method     void GetEvents (Variant)
GetFolderContents                       Method     void GetFolderContents (int, string, Variant)
GetFolderPathFromID                     Method     void GetFolderPathFromID (string, Variant)
GetFolders                              Method     void GetFolders (int, string, Variant)
GetInstanceStatusForRequests            Method     void GetInstanceStatusForRequests (int, Variant, Variant, Variant)
GetIntegrationPacks                     Method     void GetIntegrationPacks (int, Variant)
GetLatestPolicyReturnDataDefinition     Method     void GetLatestPolicyReturnDataDefinition (string, Variant, Variant)
GetLicenseExpirationTime                Method     void GetLicenseExpirationTime (string)
GetLicenseInformation                   Method     void GetLicenseInformation (int, string, Variant)
GetLogHistory                           Method     void GetLogHistory (int, string, int, Variant)
GetLogHistoryObjectDetails              Method     void GetLogHistoryObjectDetails (int, string, string, string, Variant)
GetLogHistoryObjects                    Method     void GetLogHistoryObjects (int, string, string, Variant)
GetLogObjectDetails                     Method     void GetLogObjectDetails (int, string, string, string, Variant)
GetObjectSecurity                       Method     void GetObjectSecurity (int, string, Variant)
GetObjectTypes                          Method     void GetObjectTypes (int, Variant)
GetPolicyIDFromPath                     Method     void GetPolicyIDFromPath (string, Variant)
GetPolicyInputParameterId               Method     void GetPolicyInputParameterId (int, string, string, string)
GetPolicyObjectList                     Method     void GetPolicyObjectList (int, string, Variant)
GetPolicyPathFromID                     Method     void GetPolicyPathFromID (string, Variant)
GetPolicyPublishState                   Method     void GetPolicyPublishState (int, string, int)
GetPolicyRunningState                   Method     void GetPolicyRunningState (Variant, Variant)
GetPolicyRunStatus                      Method     void GetPolicyRunStatus (int, string, Variant)
GetProductKey                           Method     void GetProductKey (string)
GetRequestOutputData                    Method     void GetRequestOutputData (int, Variant, Variant, Variant)
GetResources                            Method     void GetResources (int, string, string, Variant)
GetRunbookTesterPublishedRequests       Method     void GetRunbookTesterPublishedRequests (int, Variant)
GetVersionInformation                   Method     void GetVersionInformation (Variant)
Initialize                              Method     void Initialize ()
IsPolicyRunning                         Method     void IsPolicyRunning (int, string)
LoadObject                              Method     void LoadObject (int, string, Variant)
LoadPolicy                              Method     void LoadPolicy (int, string, Variant)
LoadResource                            Method     void LoadResource (int, string, Variant)
ModifyFolder                            Method     void ModifyFolder (int, string, Variant)
ModifyObject                            Method     void ModifyObject (int, string, string, Variant)
ModifyPolicy                            Method     void ModifyPolicy (int, string, Variant, Variant)
ModifyResource                          Method     void ModifyResource (int, string, Variant)
MoveObject                              Method     void MoveObject (int, string, string, string)
PolicyHasMonitor                        Method     void PolicyHasMonitor (int, string, Variant)
RemoveClientConnection                  Method     void RemoveClientConnection (string)
RemoveIntegrationPack                   Method     void RemoveIntegrationPack (int, Variant)
RemoveSatellite                         Method     void RemoveSatellite (string)
Replace                                 Method     void Replace (int, string, int, string, string, string, Variant)
RetrievePoliciesLinkedToAS              Method     void RetrievePoliciesLinkedToAS (string, Variant)
SetConfigurationValues                  Method     void SetConfigurationValues (int, string, Variant)
SetLicenseInformation                   Method     void SetLicenseInformation (int, string, Variant)
SetObjectSecurity                       Method     void SetObjectSecurity (int, string, string)
SetPolicyImage                          Method     void SetPolicyImage (int, string, int, Variant)
SetPolicyPublishState                   Method     void SetPolicyPublishState (int, string, int)
SetPolicyPublishStateWithParams         Method     void SetPolicyPublishStateWithParams (int, string, int, string)
SetPolicyPublishStateWithParamsAndGetID Method     void SetPolicyPublishStateWithParamsAndGetID (int, string, int, string, Variant)
SetReportingOptions                     Method     void SetReportingOptions (int, string)
StartSqmNotification                    Method     void StartSqmNotification ()
UndoCheckOut                            Method     void UndoCheckOut (int, string, int, Variant)
UpdateClientActivity                    Method     void UpdateClientActivity (string, string)

Unfortunately, these methods are not documented anywhere, so sometimes it’s a matter of trial and error to get some things working, but luckily for you I’ll save you some trouble. The good news is that the security model in place for Orchestrator is still in effect when using the COM interface, and can actually be a bit more restrictive in that for a lot of things you’ll have to be admin to use them. Most actions also require that you establish a connection handle (via the Connect method), but some methods can be used without a connection (like GetEvents). Some interfaces show up here but aren’t actually implemented or not accessible from outside code.

To show you how this stuff works, I will start out by showing you GetEvents, which doesn’t require any connection handle to work. For many of the methods, they require a “Variant Wrapper” around an object in order to create the “Variant” type the method expects. Also, you’ll frequently pass in a reference variable which becomes the output of the method, not the “return value” which is really just an HResult code.

$oismgr = new-object -com OpalisManagementService.OpalisManager
$oevents = New-Object object
$events = $events = New-Object Runtime.InteropServices.VariantWrapper($oevents)
$oismgr.GetEvents([ref]$events)
$xml = [XML]$events
$xml.OuterXml

The output of this is something like this (I formatted the XML to look better):

<Events>
<Event>
<UniqueID>{09A4CEEE-8EBE-4D1C-B5DD-06DA3EBCE01A}</UniqueID>
<Type>Information</Type>
<Computer></Computer>
<Summary>Completed Log Cleanup</Summary>
<DateTime>
129782594190000000
</DateTime>
</Event>
</Events>

So you can see how relatively simple it is to get information out of this COM interface. Of course, I would rather get things like events from the web service since it’s a little bit easier to deal with. Now let’s look at how I can perform the actions that require credentials and a connection. Basically, any of the methods that show the first parameter as an int are the ones that require a connection. For example, the GetIntegrationPacks method. The following PowerShell script will use the Connect method to create a connection handle to the COM interface and returns an integer with the connection ID. ($Username is “<domain><username>”)

$oismgr = new-object -com OpalisManagementService.OpalisManager
$ohandle = New-Object object
$handle = $hand