In the last two posts, I showed how to connect to the COM interface for Orchestrator and how to use it to get various types of information that you can’t get via the web service. But somehow I feel like I’ve been holding out on you all because one of the most-heard requests around here is how to automate the import and export of runbooks in Orchestrator. Well, wouldn’t you know it, you can actually do that with the COM interface! Import is really tough though (I’ll explain why later), but export is really easy. And, for a lot of customers who want to export their runbooks and back them up on a regular basis, just the ability to export runbooks would be awesome. Well, I’m going to show you how to do it!
Once again, if you don’t know what I mean by using the $handle or [ref]$outVar parameters, go back and read
part 1 of this series
to learn how to connect to Orchestrator’s COM interface. Of course, once you know the secrets of using these methods, repeating the process with the different methods becomes relatively simple. In this case, exporting a runbook is accomplished via the
method. Here’s what the method call in PowerShell looks like:
What I get back is XML that represents a specific runbook, but is not quite the same as the XML I would get when I export a runbook from the Runbook Designer. The difference is that when you export via COM, you get only the <Policy> node of the XML, but when you export from the Designer, the XML structure is like this:
<!-- contents of exported single runbook here -->
<!-- contents of exported global settings here -->
So in order to import the XML via the Runbook Designer, you’ll need to wrap it in the other XML elements first. That’s relatively simple in PowerShell. Here is the complete, end-to-end PowerShell script (not including the connection handle part) necessary to export a single runbook to XML in a form that is importable:
Note that in this code I removed the “EncryptionSalt” element from the XML. This is because the EncryptionSalt element is generated only by the export using the Runbook Designer, and is different each time and useless to try and use manually. Essentially, the encryption key is necessary only when taking a runbook from one Orchestration installation and importing it into another. When exporting and importing from the same database, the key is not necessary.
I do need to mention a few words about security
… When using the COM interface, there is no way to password-protect the export files like you can when manually exporting via Runbook Designer. This has one major implication:
Runbooks exported via COM from one Orchestrator database will not be able to be imported into a different Orchestrator database without stripping out all encrypted data. That is both a benefit and an issue. It’s a benefit if you’re enforcing security and don’t want encrypted data to get out accidentally. It’s an issue if you want to automate a process of moving runbooks from one place to another. If that’s the case, then what you want to do is make sure that your encrypted data is stored outside the runbooks in global variables or connection settings.
Normally, if you want to move runbooks from one DB to another, you can just use a password during export, and then when importing, specify the password again, and this lets you keep the encrypted data. But, because you can’t provide a password during the COM export, you can’t use that technique for moving runbooks. Providing a password also allows you to prevent runbooks from being copied outside your org, because if you don’t have the password, the import will fail. Exporting via COM is just like exporting without providing a password. Anyone could import the runbook on another system, but at least all encrypted data will be stripped out.
So, just keep all that in mind when you start thinking about using this for automating runbook export. Weigh the pros and cons and decide for yourself.
OK, I know I promised to talk about importing runbooks too. My advice for now, until we provide some really detailed guidance and sample scripts, is to don’t think about using the COM interface to import runbooks. The reason is that the COM interface provides access into some of the lower-level functionality, but there is a lot of work being done by the Runbook Designer behind the scenes when you import a runbook. The methods available in COM would require you to loop through every major object in a runbook and separately do imports for folders, runbooks, activities, and all global objects. The Designer also replaces all the GUIDs of objects on the fly so there’s no conflict with any existing copies of the same runbooks or activities that were imported somewhere else. It also takes care of re-using the same GUIDs or re-activating deleted objects if importing to the same location. So to put it briefly, COM works great for export, and for now don’t try to do import. I’ll continue this series with other actions, and if I get enough feedback asking for how to do import, then I can get into that (but it’s a few posts just by itself).