Automating Builds of Orchestrator Integration Packs

Overview

Like most wizard-based tools, the Integration pack wizard is designed to address common scenarios for building IPs, and may not be effective in every situation. When you need to customize the creation and installation of an IP beyond what the wizard provides, it’s helpful to understand the process behind the wizard so that you can accomplish the same thing using a customized process.

The Integration Pack Wizard streamlines the process of creating an Integration Pack (.OIP) file that is installable by the Orchestrator Deployment Manager. The .OIP file is really just a .ZIP file that has been renamed to .OIP to be easily found by Deployment Manager and avoid confusing it with other compressed files. Building the OIP involves several steps:

1. Creating metadata about the IP
2. Creating intermediate files for building the IP
3. Creating installation files used by Deployment Manager
4. Creating the MSI installer package
5. Combining the MSI and the installation files into the OIP

What’s in the OIP

You can look inside the OIP file by simply renaming the extension to ZIP and extracting the contents. The OIP file typically contains the following files:

• <IP_Name>.CAP - used by Deployment Manager to register the Integration Pack and insert the necessary information into the database for the new IP and activities to be used**<IP_Name>QIK.XML** – contains metadata used by the IP Wizard when importing existing IPs into the wizard for editing
• <IP_Name>.MSI – the file that is run by Deployment Manager on each computer you select for deployment of the IP. This MSI file installs the necessary supporting files for the activities to function when run on each Runbook Server or Runbook Designer computer. This includes:
• <GUID>Objects .XML - contains details about the IP and the activities so that the Runbook Designer can display the IP as a new category in the Activities pane.
• SC2012_Orch_Toolkit.chm – the generic local help file for the Integration Toolkit
• Merge modules that install the Toolkit libraries and other Orchestrator support files.
• Your assemblies and dependent files – the DLLs needed by the activities and other dependent files (scripts, secondary assemblies, etc.) that you specified in the IP Wizard

 

In order to create the MSI, the Integration Toolkit uses WIX (a prerequisite to installing OIT), along with an intermediate file named <IP_Name>.WSX. This WSX file instructs WIX how to build the MSI from the various components. This file is not included in the final MSI or OIP.

Shortcut to Creating the Necessary Build Files

Before you put your IP into an automated build process, you need to have the initial files (.CAP, .XML, WSX, etc.) created so they can be used as inputs to the process. However, creating these files from scratch can not only be time consuming, it can be error prone and lead to installation or usage failures related to the build, not related to your code.

The best method for initially creating the necessary files is to let the IP Wizard do it for you. When the IP Wizard builds an IP, it creates and packages the files, and many of the files you need can be obtained from an installed Integration Pack. However, there are several intermediate files that are also needed that are not available from an installed IP. So in order to obtain these intermediate files, you need to “intercept” the IP Wizard’s build process.

When you run the IP Wizard, it stores the intermediate files in a temporary directory here:

C:\Users\username>\AppData\Local\Microsoft System Center 2012\Orchestrator\Integration Toolkit

To capture the intermediate files created by the wizard:

1. Open Windows Explorer and browse to the directory shown above
2. Right-click the directory name and select Properties.
3. In the Properties dialog, select the Security tab
4. Click the Advanced button below the Permissions list.
5. In the Advanced Security Settings dialog, on the Permissions tab, click the Change Permissions button.
6. Select the current user account, or if your account is in a group, select the group, then click the Edit button.
7. In the Permissions list, scroll down and select the Deny checkbox for “Delete” and “Delete subfolders and files”, then click OK.
8. Click OK, then click Yes on the warning dialog. Click OK to return to the Properties dialog.
9. Click OK to close the properties dialog.
10. Run the IP Wizard as you usually would to create an IP. When the IP Wizard begins building the IP, you will see a new directory get created under the Integration Toolkit directory you just modified. The process will fail at the end because it cannot delete the temporary directory.
11. You should see a list of files in the new temporary directory containing .cap, .msi, .wixobj, .wixpdb, .wsx and .xml files.
12. For the build process you will need the XML, CAP, and WSX files. Move these files to a folder in your source control project, such as “XML” (the name is not important).
13. Be sure to go back into the properties of the Integration Toolkit directory and remove the Deny restrictions that you put in place above.

Creating the Source Control Project Structure

Assuming you’ve already created a project in source control for your Integration Pack, you will need to add directories and files to it in order to complete the IP build process. For this example, we’ll use the following project directory: ** $/TFSProject/Main/MyIP**

Adding the Installer Project

You will need WIX installed on your development machine along with the Visual Studio integrations. It can be done without the integrations or on other platforms, but that won’t be covered here. To add the installer project:

1. Open your IP solution in Visual Studio
2. Right Click the solution in the Solution Explorer and select Add > New Project.
3. Under Installed Templates, select Windows Installer XML, and in the middle pane, select Setup Project. Name the project as needed and ensure the directory path is where you want it (for this example, we’ll use the parent project directory).
4. Click OK. The project is created and a default WSX file is added and opened for editing.
5. Close the WSX file and remove the WSX file from the project.
6. Copy the WSX file created by the IP Wizard into the directory, and add it to the project.

Other Required Files for the Installer

You may notice that there are several other files needed during the building of the MSI that are not found in the temporary directory. These files are:  

• SC2012_Orch_Toolkit.chm
• Icon.ico
• Microsoft.SystemCenter.Orchestrator.Integration.Net.msm
• Microsoft.SystemCenter.Orchestrator.Integration.Core.msm 

These files are included in the Integration Toolkit, and are installed into the Integration Toolkit\Bin directory under the Orchestrator installation root folder, typically here:

C:\Program Files (x86)\Microsoft System Center 2012\

You should copy these files into your installer project so they are linked inside source control with the project.

Adding the Metadata Files

The metadata files include the CAP and XML files that are either included in the MSI or the OIP file.

1. Create a new folder in your project named “XML Files” (you can name it anything, this is just an example).
2. Copy the two XML files and the CAP file created by the IP Wizard into this directory and add them to the project.

Updating the Build Process

Assuming that your build process will now automatically create the MSI because it’s a sub-project of the overall solution for the IP, all you have to do is update the build process to create the OIP file.

Creating the OIP File

The following script will take the appropriate files and package them into a ZIP file, then rename to OIP. This script requires the following:

-       It is called with 5 command line parameters (%1 through %5)

-       Zip.exe (command-line ZIP) is located in the directory you specify for parameter 1

-       The MSI is already built and available in the directory you specify in parameter 2

-       The SolutionRoot parameter (param 3) is the parent directory of your IP’s solution directory

-       Your IP Base name (i.e. MyIp) is used for your MSI file and the folder name of your IP project

setlocal set BldTool=%1 set RelPath=%2 set SolutionRoot=%3 set IpBaseName=%4 set OipName=%5 set StageDir=%RelPath%\OipStage rem SolutionRoot = “$/TFSProject/Main” in this example rem Stage the files to be zipped rem Assumes MSI is already built and exists in release path if exist "%RelPath%\*%IpBaseName%*.msi" (     xcopy /y "%RelPath%\*%IpBaseName%*.msi" "%StageDir%\" ) else echo MSI is missing in "%RelPath%" Rem Copy CAP file if exist "%SolutionRoot%\%IpBaseName%\XML\*cap" (     xcopy /y "%SolutionRoot%\%IpBaseName%\XML\*.cap" "%StageDir%\" ) else echo cap is missing in "%SolutionRoot%\%IpBaseName%\XML" Rem Copy Objects.Xml, QIK.XML files if exist "%SolutionRoot%\%IpBaseName%\XML\*xml" (     xcopy /y "%SolutionRoot%\%IpBaseName%\XML\*.xml" "%StageDir%\" ) else echo xml files missing in "%SolutionRoot%\%IpBaseName%\XML" Rem Copy EULA file if exist "%SolutionRoot%\%IpBaseName%\XML\*eula" (     xcopy /y "%SolutionRoot%\%IpBaseName%\XML\*.eula" "%StageDir%\" ) else echo EULA file missing in "%SolutionRoot%\%IpBaseName%\XML" pushd "%StageDir%" "%BldTool%\zip.exe" -9 "%RelPath%\..\%OipName%.oip" *.* popd endlocal

Your build process now simply needs to call this script to automatically generate the OIP file.