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:
- Runbook Parameters
- Runbook Instances
- Runbook Instance Parameters
- Activity Instances
- Activity Instance Data
- Runbook Servers
- Runbook Diagrams
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!):
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.
The output of this is something like this (I formatted the XML to look better):
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>”)