Understanding IP Installation: What Does Register/Unregister/Deploy/Undeploy Really Mean?

Understanding IP Installation: What Does Register/Unregister/Deploy/Undeploy Really Mean?

  • Comments 2
  • Likes

One of the most foundational activities an Orchestrator admin does is installing Integration Packs. After all, Integration Packs provide the real value to Orchestrator because they allow you to extend its capabilities and let you connect to virtually anything so you can automate and orchestrator across many different platforms. However, just because it’s one of the more common activities doesn’t mean most admins really understand it. In fact, it’s one of the more misunderstood parts of the platform. Hopefully here I can shed a little light on how it all works (and why it works the way it does, even if it might not be the way you expected).

Installing an IP

When you install a new IP, the process involves two distinct steps:

1. Register the IP

Deployment Manager opens up the OIP file (which is actually just a renamed ZIP file) and extracts several things – a .CAP file, an .MSI file, and some other things like the EULA. The .CAP file is an XML file that the Deployment Manager uses to import the right data into the CAPS table in the Orchestrator database. The CAPS table simply defines the Integration Packs’ names and IDs so they can be located for further actions. The CAP file also contains information that defines other tables where the activities themselves are defined, along with SQL scripts to effect the appropriate database changes. Deployment Manager then renames the OIP file to the product ID and saves it to the “C:\Program Files (x86)\Common Files\Microsoft System Center 2012\Orchestrator\Management Server\Components\Packs” directory, and saves the MSI file to the “C:\Program Files (x86)\Common Files\Microsoft System Center 2012\Orchestrator\Management Server\Components\Objects” directory.

2. Deploy the IP

Once the IP has been registered, it has to be deployed to every Runbook Designer and Runbook Server that needs to have it. Deploying the IP involves Deployment Manager copying the file to the remote computer (if not the current computer) and using msiexec.exe to install the MSI file. This would be essentially the same as you copying the file to the machine and double-clicking on the MSI file. When the MSI installs, it verifies that the computer it’s installing on is a Runbook Designer or Runbook Server (it won’t install anywhere else). The installer creates a registry key here: “HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\SystemCenter2012\Orchestrator\IPs”. This is used by the Deployment Manager to quickly determine which machines have the IP installed. An XML file in the MSI is copied to “C:\Program Files (x86)\Common Files\Microsoft System Center 2012\Orchestrator\Extensions\”. This MSI contains definitions for the IP and activities used by the Runbook Designer to know how to display the category and activities. The remaining files in the MSI, including the assemblies and dependent files, are copied to “C:\Program Files (x86)\Common Files\Microsoft System Center 2012\Orchestrator\Extensions\Support\Integration Toolkit” into a subdirectory named with the product ID guid.

Upgrading an IP

When you upgrade an existing IP, you have to first uninstall, or un-deploy, the IP from the Runbook Designers and Runbook Servers where it is installed. This is because if any files from an IP are in use when the new version is installed, installation will fail or cause a reboot of the computer. It could leave your server in a bad state or worse, reboot a runbook server at the most inappropriate time.

Once you uninstall, you do not unregister. IPs have built-in knowledge on how to upgrade an existing version (this code was enhanced for Orchestrator 2012 to fix issues and limitations with Opalis 6.3’s upgrade process). However, if you unregister the IP, you can end up defeating the upgrade logic and wind up with a bad installation. The proper course of action is to simply register the new IP with the previous version still registered. Then you simply deploy the IP out to the Runbook Designers and Runbook Servers again.

Uninstalling an IP

So what happens when you just want to get rid of an IP? Maybe you created a brand new version of an IP that doesn’t upgrade from the old version – it is a new IP. You want to remove the old IP, so you uninstall the IP from the Runbook Designers and Runbook Servers, and you unregister the IP. SO what happens when you do that? Well when you uninstall, it’s pretty simple. It just uninstalls the MSI from the appropriate computers. When you unregister the IP, all it does it remove the OIP file from the “Packs” directory mentioned above. That’s all. I know, right now you’re saying “WHAT???” Why doesn’t it remove the information from the database too?

When we were planning Orchestrator 2012, we also questioned this and wondered why we wouldn’t clean out the database to put it back the way is was before the IP was installed. Basically, this would have left the DB in a cleaned-up state. The thing was, we decided that it wasn’t appropriate for us to determine arbitrarily to delete information from a customer’s database. After all the data associated with the IP and its activities includes runtime data, can include valuable published data and auditing information, and if we simply deleted that data, we would make some customers very unhappy! So, we eventually decided to not change the behavior that existed in Opalis 6.3 so that the data would be retained. Now this decision had repercussions in the other direction in that leaving all this data in the database could lead to issues with re-installations of the IP or future versions of the IP, but those would likely be few.

The biggest issue with leaving deleted activity and IP information in the database is simply that the DB can potentially bloat with data that is no longer used and not readily accessible. In a future post, I’ll show you a tool I created for helping remove this bloat. The key is that you control what gets removed rather than it being arbitrarily removed during IP unregistration.

By the way… since you know that unregistering an IP simply removes the OIP file, if you ever accidentally unregister an IP, all you need to do is replace the guid-named OIP file back in the “Packs” directory and it will appear as registered again!

Hopefully this has helped shed some light on the potentially confusing process of IP installation and uninstallation in Orchestrator 2012. As always, keep the comments and suggestions coming!

Your comment has been posted.   Close
Thank you, your comment requires moderation so it may take a while to appear.   Close
Leave a Comment
  • When deploying an IP to a remote Designer, what permissions are required on both the Management Server (Deployment Manager) and the Designer host?  I get 'Access denied' for some Designers but haven't determined the pattern.

  • Hi Robert,

    first off, thanks for your inspiring work about automating an automation product that's not making it terribly easy to let itself be automated.
    I used your script at http://blogs.technet.com/b/orchestrator/archive/2012/05/24/more-fun-with-com-importing-integration-packs-via-powershell.aspx as a basis for my own implementation and I noticed some differences on how an IP is registered (SCO2012SP1, SCO2012R2).

    "1. Register the IP"
    "Deployment Manager then renames the OIP file to the product ID" - this is only correct for some IPs, where the msi product ID happens to be the same as the IP's Unique ID. Deployment Manager renames the OIP file to the UniqueID of the IP (as defined in the CAP file).
    An example for an IP where the UniqueID and the msi's Product ID differ is the "System Center Integration Pack for Windows Azure" from SCO2012R2.
    Accordingly, the ProductName that needs to be added to the CAP file before AddIntegrationPack has to be the UniqueID as well (plus the ".OIP" extension, which seems to be missing in your script).

    "Deployment Manager then renames the OIP file to the product ID and saves it to the 'C:\Program Files (x86)\Common Files\Microsoft System Center 2012\Orchestrator\Management Server\Components\Packs'"
    Not only that, but DM removes the "Read-Only" attribute as well, if it happens to be set on the source OIP file. When trying to unregister an IP in Deployment Manager where the OIP is Read-Only, the unregistering just fails silently, without an error message.

    "2. Deploy the IP"
    "The installer creates a registry key here: 'HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\SystemCenter2012\Orchestrator\IPs'."
    One word of caution: the names of the keys here are NOT necessarily the names of the IPs, even though it looks like it at first glance. The key name is actually the msi's ProductName property, which may differ from the IP's name (example again the "System Center Integration Pack for Windows Azure" from SCO2012R2, where the msi ProductName (and registry key) is "System Center Integration Pack for Azure" (note the missing "Windows" in front of "Azure").

    "Function Get-MsiProperty"
    The ComObject doesn't clean up after itself when the function ends; a handle to the msi file queried remains open until the PS console where the command was run is closed.
    Before "return $msiProp", two commands need to be added:
    [Runtime.InteropServices.Marshal]::FinalReleaseComObject($View) | Out-Null
    [Runtime.InteropServices.Marshal]::FinalReleaseComObject($wiDatabase) | Out-Null


    And finally one question that you can maybe solve:
    Some IPs, like SC2012R2_Integration_Pack_for_Configuration_Manager.oip (http://www.microsoft.com/en-us/download/details.aspx?id=39622), include a file "InstallInfo.ini". It seems to provide information about further actions to take when installing the msi; so far, I've only found "UninstallOld=FALSE" (no section name).
    Did you happen to come across documentation about the function and format of this file?