Creating a Custom Installer for Windows (MSI)

Overview

Identity Finder is distributed from the IdentityFinder.com website as an executable application which may be installed by double-clicking on IdentityFinderSetup.exe. The installer application is a wrapper around a standard Windows Installer package (msi file). It is often desirable to customize this package to include custom settings and configuration options such as the information necessary to communicate with the enterprise console or to prevent shortcuts from appearing on the Windows desktop. This article provide the tools necessary to automate the process of customizing the msi. Manual editing of the MSI is not supported.

This article contains the following topics:

Using MSIBuilder to Automatically Edit an MSI
Testing Installer Packages
Silent Installation
Troubleshooting
Command Line Interface Reference
Additional Resources
Attachments

Using MSIBuilder to Automatically Edit an MSI

The MSIBuilder application provides a GUI to easily customize the installation package for example, to include a license file and specify settings.

To open the MSIBuilder, follow these steps:

Ensure that .NET Framework v2.0 or later is installed on the computer that will run the MSIBuilder application.
Click on the link for IdentityFinderMSIBuilder.zip at the bottom of this article, save it on the local computer and unzip the contents into a new folder.
Navigate to the folder used in step 2 and double click on IdentityFinderMSIBuilder.exe.

To create a custom installer package, follow these steps:

Obtain the license file, identityfinder.lic, issued by Identity Finder. This file is optional and only required when it is desirable to ensure that the application is licensed during the installation process. This file is not required when using activation numbers.
Obtain the 32 bit Console registry settings from the enterprise console by navigating to http://consoleserver/Services where consoleserver is the name or IP address of the enterprise console and saving the 32 bit registry settings to the local machine as ClientSettings.reg.

Note: The 32 bit registry settings must be used even if the target platforms are 64 bit.
Obtain the desired or latest version of Identity Finder Enterprise Client for Windows.
Optionally obtain the OCR module files. Note, OCR will only be enabled if the license or activation number includes this module.
Complete the relevant fields in the MSIBuilder GUI (details below image):
- Client Installer Exe - (Required): The full path to IdentityFinderSetup.exe. As an alternative to manually downloading the file and providing the full path, the button labeled, "Download" may be used to automatically download the latest version from the Identity Finder web site and populate the field.
- Output File - (Required): The name and path of the resulting customized MSI.
- License File: The full path to the identityfinder.lic file.
- Registry File: The full path to the ClientSettings.reg 32 bit registry settings file obtained from the console.
- Include OCR Files: Specify whether or not to include the OCR files and, if so, the full path to the ocr.zip file containing the files necessary for the installation of the OCR module. In order for the OCR module to be used, the license must include OCR.
- Install Endpoint Service: Specify whether or not the Identity Finder Endpoint Service should be installed. When using the client with the enterprise console, this box must be checked or communication with the console will fail.
To configure additional, advanced settings to control the installation experience, click the configure button. When the Configure Advanced Options dialog is displayed, the default value for each property is displayed.
- Installer UI Options -> Suppress user configuration on installation: Install the application without allowing the end user to customize any settings. A simple progress bar with a cancel button will be displayed.
- Installer UI Options -> Installation modes: Allow All (default) allows the user to select Typical or Custom setup type. It is also possible to force the user to select Typical (by disabling Custom) or Custom (by disabling Typical). If a user can access the Custom Setup, they will be able to turn on and off the installation of shortcuts, the endpoint serivce, and other features.
- Installer UI Options -> Display Endpoint Service Feature: Shows the Endpoint Service feature in the UI of the installer allowing a user to enable or disable the installation of the service. This setting is only available when Install Endpoint Service is checked on the main dialog and the Suppress user configuration on installation setting is not selected (as it does not apply in those cases).
- Installer UI Options -> Uninstall user settings: Display the prompt "Would you like to remove your user settings?" to the user on uninstall. Alternatively force settings to be saved during uninstall or force them to be removed - both without a user prompt.
- Shortcuts -> Add Start Menu Shortcuts: Add a program group to the Start menu containing shortcuts to IdentityFinder.exe, the online help page, and the Password Vault. Checking this box will set the option to be enabled within the installer, but a user with access to the Custom Setup button will be able to disable the creation of shortcuts.
- Shortcuts -> Add Desktop Shortcuts: Add a shortcut to IdentityFinder.exe on the current user's desktop. Checking this box will set the option to be enabled within the installer, but a user with access to the Custom Setup button will be able to disable the creation of shortcuts.
- Windows Integration -> File Associations: Associate .idf and .idfvault extensions with the application allowing users to double click on saved results files and/or file vault files to launch Identity Finder and automatically load the specified file.
- Windows Integration -> Explorer Integration: Add a right click menu for drives, files, and folders that provides direct access to search, secure, and shred capabilities without having to first launch the Identity Finder application. The options available via the right click menu can be customized via client application settings.
- Launch Options -> Launch Identity Finder After Installation: At the conclusion of the installation wizard, an option is displayed to allow the user to open the client application. When this option is checked in the MSIBuilder, the user will be able to launch the application by clicking Finish or clear the checkbox to prevent the application from launching. Alternatively, force the user to launch the application by preventing them from unchecking the box.
- Launch Options -> Apply command line options to: Command line options can be added to change the behavior of the application. The options can be added for the initial launch from the last page of the installation wizard and/or to the desktop and start menu shortcuts.
- Launch Options -> Job Mode: Start Identity Finder in Job Mode. For more information, refer to http://www.identityfinder.com/kb/157232
- Launch Options -> Configuration File: Start Identity Finder with an XML configuration file. Provide the full path including drive letter or share name and filename to the location that will contain the configuration file. This option does not install the configuration file. For more information, refer to http://www.identityfinder.com/kb/157232. Note: this is only recommended for users without the DLP Console.
- Launch Options -> Password Vault: Launch the Password Vault. For more information, refer to http://www.identityfinder.com/kb/157232.
- Additional Files: Any additional file can be installed to the same location as IdentityFinder.exe. The only file that has an impact on the application is activation.txt. For more information, refer to http://www.identityfinder.com/kb/182407#activation.

Click the Build MSI button. When the MSI is created, "Finished!" will be displayed to the left of the button labeled, "Build MSI".
Test the completed installation package.

Testing MSI Packages

Because changes to the MSI must be made exactly according to Microsoft's requirements, any invalid input file (e.g., incorrect license file, invalid registry settings file) or typographical or formatting error could cause the installer to fail. Therefore, it is critical to test the complete package prior to deployment. To test the installer package, complete the following steps:

Launch the MSI by copying it to a test workstation and double-clicking on it.
Complete the installation wizard and allow the installation to finish. If the MSI fails to successfully complete the installation, reference the Troubleshooting section below.
Launch the Identity Finder client. If a license file, identityfinder.lic, was included in the installer, the activation screen should not be displayed. If the activation screen is displayed then the license provided was either invalid or expired. Contact whomever provided identityfinder,lic and have them consult with the sales team to determine the licensing issue.
Run a search on the test workstation and ensure that some results are found. If the test workstation has no data on it, test data may be downloaded and placed on the system for testing purposes.
If communication with the enterprise console was part of the installer packager, wait 10 minutes after the search with results completes and the client has been closed. Log in to the console and review the results from the test run. If the results do not appear in the console, perform the appropriate troubleshooting steps to determine the issue.

Silent Installation

The Windows Installer, responsible for installing MSI packages, has a variety of installation and removal options. Many desktop management and deployment systems integrate directly with the Windows Installer to provide options for silent installation though though it may be necessary or desirable to invoke silent installation or removal of an MSI manually from the command line. The following command line will launch an MSI installation without displaying any user interface:

msiexec /i IdentityFinder-CompanyName.msi /qn

Where "IdentityFinder-CompanyName.msi" is the full path and name of the MSI. The "/qn" at the end of the command line instructs the Windows Installer to set the User Interface level to "No UI". For further command line options available from the Windows Installer, please review the official Microsoft documentation.

Troubleshooting

There may be errors when attempting to install the MSI. This section will address common errors encountered as well as steps to perform if the MSI does not install properly.

MSI Installation Failure

To address issues identified during an MSI installation, it is necessary to review the MSI errors. To review the errors, instruct Windows Installer to create a log file by launching the installer from the line as follows:

Open a command prompt and navigate to the directory where the MSI is located. In this example, the MSI is located in "C:\IdentityFinderMSI\IdentityFinder-CompanyName.msi". At the command prompt type the following command:
```
IdentityFinder-CompanyName.msi /l*vx log.txt
```
Where "IdentityFinder-CompanyName.msi" is the name of the custom MSI.
Perform the installation steps until the error is displayed and then exit the installer.
Open the file, "log.txt" which was created in the same folder as the MSI and review its contents. In most cases searching for the word "error" will yield the specific error that caused the installation to fail.
Perform an Internet search for the error by error number/code and error text. The results will usually yield information about the issue. It may be necessary to consult with a qualified Windows system administrator or Windows Installer (MSI) expert to resolve the issue.
If the MSI was created only using MSIBuilder and no other edits were made, open a support ticket to address the issues. Please be sure to include the log created in steps 1 and 2 above, a screen shot of the error dialog that is displayed during the MSI installation, and a link to a downloadable copy of the MSI (post the MSI somewhere on a publicly facing web site where the Identity Finder support team can access it for reference, if necessary). If custom edits were made, they are not supported by our support team and must be addressed by the individual that edited the MSI.

Command Line Interface Reference

All of the functions and settings available via the GUI are also available via a command line interface. The main items are available via switches and the advanced options may be specified in an xml configuration file. Please refer to the GUI section(s) above for descriptions of each setting. Please refer to the file AdvancedOptionsConfiguration.xml in the IdentityFinderMSIBuilder.zip in the Attachments section of this article for a sample advanced configuration file.

IdentityFinderMSIBuilder.exe -Installer "C:\IdentityFinderMSI\IdentityFinderSetup.exe" -Output "C:\IdentityFinderMSI\IdentityFinderCompanyName.msi" [-License "C:\IdentityFinderMSI\IdentityFinder.lic"] [-RegSettings "C:\IdentityFinderMSI\ClientSettings.reg"] [-OCRFiles "C:\IdentityFinderMSI\OCR.zip"] [-EPS|-NoEPS] [-Advanced "C:\IdentityFinderMSI\AdvancedOptionsConfiguration.xml"] [-Quiet]

Notes:

All file paths must be enclosed within quotes.
The -Installer and -Output switched are the only required switches (this is the same as when using the UI).
If a full path is not provided to the -Output switch, the msi will be created in the same folder as IdentityFinderSetup.exe.
The Endpoint Service is installed by default when using the MSIBuilder, so the service will be installed if neither -EPS nor -NoEPS is specified.
The -Quiet switch will prevent status messages from being displayed in a console windows. A log file, IdentityFinderMSIBuilder.log, will be created in the folder where IdentityFinderMSIBuilder.exe is located
The configuration file supports one or more settings that are not part of the UI. These settings are documented with the sample xml configuration file.

Additional Resources

Getting Started with the Enterprise Suite

Attachments

IdentityFinderMSIBuilder.zip (updated 4/26/2012)