STW Installations Dealer Technical Information Dealer Silent Distribution Prepared for Marketing & Product Support Division Caterpillar Inc.
Documentation Information and Revision History File Name Original Author Version 1.0 2.0
Date 4/1/2009 4/5/2010
STW2010A_Silent_Distribution.doc Caterpillar Inc. Author Daniel Gabrielse Daniel Gabrielse
Revision Notes Initial Version 2010A Updates
Certain parts of this document a nd the information herein are the property of Caterpillar Inc. and may not be reproduced, Disclosed, revealed or used except in accordance with the executed license agreement with Caterpillar or its authorized
2
Sub licensor. This document may contain materials and information that were not prepared or reviewed by Caterpillar.
3
Table of contents TABLE OF CONTENTS.............................................................................................................4 1 INTRODUCTION......................................................................................................... ........... 5
1.1 PURPOSE..................................................................................................................................5 1.2 SCOPE......................................................................................................................................5 2 STW 2008A (AND PRIOR) ISSUES........................................................................................6
2.1 SUPPORT DROPPED FOR 2008A..............................................................................................6 2.2 STW MASTER I NSTALLER 2008A...........................................................................................6 2.3 DESIGN DEFICIENCIES .............................................................................................................6
2.3.1 Install Management.............................................................................................6 2.3.2 Uninstall Keys.....................................................................................................6 2.4 I NSTALL LOCATIONS...............................................................................................................6 3 STW 2010A DESIGN........................................................................................................... .....8
3.1 DISC STRUCTURE....................................................................................................................8 3.2 STW MASTER I NSTALLER ......................................................................................................8 3.3 DEFAULT NEW I NSTALL LOCATION........................................................................................8 3.4 DEFAULT UPGRADE LOCATION...............................................................................................9 3.5 I NSTALL DESIGNS – MSI........................................................................................................9 3.6 R ESULT CODES........................................................................................................................9 3.7 LOGGING...............................................................................................................................10 4 INSTALLATION AUTOMATION........................................................................................11
4.1 OVERVIEW.............................................................................................................................11 4.2 SETUP PREREQUISITES ..........................................................................................................11 4.3 R ESULT CODES......................................................................................................................11 4.4 APPLICATION I NSTALLATION COMMANDS............................................................................11 4.5 STW UPGRADE MAINTENANCE............................................................................................13
4.5.1 Licensing Changes – 2009A and Older............................................................14 4.5.2 Licensing STW 2009B to STW 2010A............................................................14 4.5.3 Licensing STW 2009B to STW 2010A............................................................14 4.5.4 Support Applications – STW 2008A (and Older).............................................14 4.5.5 Pre Upgrade......................................................................................................15 4.5.6 Upgrade ............................................................................................................16 4.5.7 Post Upgrade.....................................................................................................16 4.6 LOGGING...............................................................................................................................17 4.7 NETWORK I NSTALL ISSUES...................................................................................................18
4.7.1 SIS DVD – Certinstall.exe................................................................................18
4
1
Introduction 1.1 Purpose The purpose of this document is to communicate technical information relating to the installation functionality of the STW software suite. Specifically, this document describes how to install the applications in a silent mode, with their various requirements. The goal of this document is to help enable dealer IT staff implement silent, autonomous, centralized distribution of the STW product suite without the interaction of the end user.
1.2 Scope This document contains information specific to the installation of all applications within the STW product suite. These include STW 2008A (legacy application), STW Launchpad, Service Report, SIS DVD, Cat Electronic Technician, Technical Analysis (TA), Component-Based Troubleshooting (CBT), and DBS Upload Utility.
5
2 STW 2008A (and Prior) Issues 2.1 Support Dropped for 2008A Beginning with the 2010A release of the STW suite of applications, upgrades from the 2008A (and prior) releases of STW are no longer supported. The information listed below is maintained in this document for historical sake. Any attempt to upgrade from the 2008A release will result in a failure bo th from the Master Installer, as well as from the independent installations (setup.exe). If an installation from the 2008A timeframe does still exist on the target PC, it must be fully uninstalled prior to continuing. While the tools and procedures provided in the past to uninstall these releases still continues to function, Caterpillar Inc. will no longer provide official support to resolve any issues that may result from implementing.
2.2 STW Master Installer 2008A Prior to the 2009A release, STW Master Installer acted a s an installing application, which happened to install other applications along the way. This design was implemented originally in 1999 with the original release of STW. The effect was the user only saw a single application install, with licensing and validations all being performed by the centrally by the Master Installer.
2.3 Design Deficiencies
2.3.1 Install Management The 2009A STW Master Installer, which is itself an InstallShield Setup.exe, ex ecuted each application install through by calling a command line. The effect is that a single application’s setup.exe install calls all of the other application installs.
2.3.2 Uninstall Keys Past releases introduced non-standard designs in order to solve some technical issues. Most important is the uninstall functionality. STW removed the uninstall string from the normal location, and placed them under the STW HKLM product key. This design introduced a number of issues over time, and the new install places it back into a proper working state. Each application will be handled as a stand-alone application, with proper uninstall strings available in the proper location. Each application may be uninstalled using the standard Windows Control Panel “Add/Remove Programs” dialog.
2.4 Install Locations The STW 2008A product suite allowed the end user to alter the default location to install an application. Each application had a registry key that specified the install directory. Each application also had a default directory to be installed.
Application Install Locations – STW 2008A
6
Application STW
Default Install Path
Registry
Cat ET
Default Registry Default
SIS DVD Service Report
Registry Default Registry Default
CBT
Registry
TA
Default Registry
Data Technician
Default Registry Default
Upload Utility
Registry
FFS
Registry
SIS OLE Server
Default
Default Registry Default
HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\Service Technician Workbench\location C:\Program Files\stw HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Caterpillar Electronic Technician C:\Program Files\Caterpillar Electronic Technician HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\0F\location C:\Program Files\Caterpillar Inc\SIS HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\Service Report\Directory C:\Program Files\Caterpillar Inc\Service Report HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\0E\location C:\Program Files\Caterpillar Inc\CBTOleServer HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\0D\location C:\Program Files\STW HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\10\location C:\Program Files\Caterpillar Inc\DataTechnician HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\SIMS DBS Upload Utility\Location C:\Program Files\Caterpillar Inc\SIMS DBS Upload Utility\bin HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\0B\location C:\Program Files\ffs HKEY_LOCAL_MACHINE\SOFTWARE\Caterpillar Inc.\STW\Master Install\0C\location C:\Program Files\Caterpillar Inc\SISOLEServer
7
3 STW 2010A Design 3.1 Disc Structure The STW install disc contains the following directories:
Directory
Root MasterInstaller_[Buil d Number] CBT Ctech Dataview Dotnetfx ET M300 Service Report SIS STW Launchpad TA TA Pocket PC Upload Utility Windowsinstaller3_1
Directory Structure Description Location of the Setup EXE for the Master Installer Operational and translation files for the Master Installer
Location of Component-Based Troubleshooting (CBT) install. Location of Challenger Technician install Location of Data View install Location of Microsoft .Net 2.0 installation used by the Master Installer Location of Cat Electronic Technician install Location of M300 application install Location of STW Service Report install Location of Service Information System install Location of STW Launchpad install Location of Technical Analysis install Location of Pocket PC version of TA Location of DBS Upload Utility install Location of Windows Installer; used by the Master Installer
3.2 STW Master Installer The Master Installer (MI) is a front-end utility used to install the user-selected applications. It is a .Net-based application using Microsoft Click-Once packaging. The utility may be called from the physical media (DVD), or it may be copied to a network for users to call the install.
3.3 Default New Install Location The following lists the default location of each application on a new install. These locations are different from the 2008A releases, in order to comply with the Caterpillar IT software development requirements. While not required for proper execution, Caterpillar Inc. does recommend using these locations for all implementations.
Application STW Launchpad Cat ET
Application Install Locations – STW 2009A Install Path %PROGRAMFILES%\Caterpillar\STW Launchpad\ %PROGRAMFILES%\Caterpillar\Electronic Technician\
8
SIS DVD Service Report CBT TA Upload Utility
%PROGRAMFILES%\Caterpillar\SIS\ %PROGRAMFILES%\Caterpillar\Service Report\ %PROGRAMFILES%\Caterpillar\CBT\ %PROGRAMFILES%\Caterpillar\TA\ %PROGRAMFILES%\Caterpillar\Upload Utility\
3.4 Default Upgrade Location Application Install Locations – STW 2008A Upgrade Application Install Path Cat ET Maintains old path SIS DVD Maintains old path %PROGRAMFILES%\Caterpillar\Service Report Service Report %PROGRAMFILES%\Caterpillar\CBT CBT %PROGRAMFILES%\Caterpillar\TA TA %PROGRAMFILES%\Caterpillar\Upload Utility Upload Utility
3.5 Install Designs – MSI All installations launched via the MI utilize standard Microsoft Windows Installer file formatting. Each application leaves the MSI exposed on the disc, rather than compressing it in the setup.exe. The MI will call each install via the setup.exe, but this method is not required for the applications to be installed. For more information on Windows Installer file formats, and how to utilize them, please reference the Microsoft documentation.
3.6 Result Codes All applications within the STW Suite utilize standard MSI result codes. Standard values include the following:
Value 0 3010
Install Result Codes Description Install completed successfully, application is ready to be used Install completed successfully, restart is required before use
The MI utility allows for installs to fail, and attempts to call the install in a full-UI mode to allow the user to try to handle the error. This scenario is expected to occur in the case of an invalid license on the PC for Cat ET. Other results are possible, specifically if a different instance of Windows Installer is currently running, or if an install fails. A good reference document is located here: http://msdn.microsoft.com/en-us/library/aa368542.aspx
9
3.7 Logging In order to account for future issues during support, the MI directs each application, via a command line statement, to create a log file and output the log to a standard location. The location is as follows: %ALLUSERSPROFILE%\Application Data\Caterpillar\Installer\
When the install is started, the MI directs each application to use verbose logging. This can use up a larger amount of space, and may be deleted prior to an upgrade without issue. Each new install, upgrade or repair will create a new log file in addition to any existing log files. /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\[Application][timestamp].log"
Please note: the target directory for the log must exist prior to initiating the install. If this directory does not exist, the install may fail.
10
4 Installation Automation 4.1 Overview With the design changes beginning with the 2009A release, performing silent installs with 3rd party packages has become significantly easier to implement. Using command line implementations, it is possible to apply many customizations to an install. Each install is currently implemented using Windows Installer command line values. While these customizations are possible, these changes are to be performed at the dealer’s risk.
4.2 Setup Prerequisites Most installations in the STW suite provide both the setup.exe and the MSI file. This allows the install to be called using both. The main purpose of a Setup.exe is to install any prerequisites needed for the MSI to complete the install. If using the MSI command line, any setup prerequisites will not be installed, and must be installed prior to a successful install. Prerequisites to an install are noted where applicable.
4.3 Result Codes Third-party install packaging and distribution tools typically have the ability to retrieve the result code returning from the application install. Responding to the result codes is necessary in order to guarantee a proper install and upgrade. A likely scenario would be the required restart of the PC in order for the licensing mechanism. If the restart is not performed, it is likely that the application will not perform properly.
4.4 Application Installation Commands Following is a listing of the command line statements that may be used to execute a silent install. The sections include both the Setup.exe command line as well as the MSI command line. The IT organization may choose to implement either version. For the most part, all of the command lines for the installs are identical except for log file locations. During upgrade, a different command line may be required for the application to function properly. Where necessary, the upgrade command line is noted. STW Launchpad Setup Prerequisites Comments Setup EXE command line MSI command line
None Standard MSI install, no custom actions required Setup.exe /s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\STW Launchpad.log"" STW Launchpad.msi /qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\STW Launchpad.log"
11
Cat Electronic Technician Setup Prerequisites Comments
Setup EXE command line
MSI command line
None The Cat ET install may actively prompt to restart the PC in some cases. During testing, we noted that it could possibly force a restart from silent. As a precaution, we recommend telling the install not to force the reboot with the command line statements below. /s /v"/qn RebootYesNo="No" Reboot="ReallySuppress" /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\Electronic Technician.log"" /qn RebootYesNo="No" Reboot="ReallySuppress" /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\Electronic Technician.log"
SIS DVD Setup Prerequisites Comments Setup EXE command line MSI command line Upgrade Command
Setup Prerequisites Comments
Setup EXE command line MSI command line
Setup Prerequisites Comments
None The upgrade installation requires additional command line parameters be set. Please see below. /s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\SIS DVD.log"" /qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\SIS DVD.log" /s /v"/qn REINSTALL=ALL REINSTALLMODE=vomus /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\SIS DVD.log""
Service Report Microsoft Dot Net 3 Standard MSI install, no custom actions required. Because Microsoft .Net 3 is required, this install may take longer to perform. For dealerships using an automated distribution system such as SMS or LanDesk, pushing the .Net 3 package out earlier can reduce time during the application install. /s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\STW Service Report.log"" /qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\STW Service Report.log"
Technical Analysis Microsoft Visual C++ Redistributable: vcredist_x86.exe TA installs the Crystal Reports printing engine, which in some
12
circumstances fails if vcredist_x86.exe is not installed first. This issue is at present known to be a Microsoft Vista-related issue. If Cat ET is installed first, the required files will already be installed, and this package is not required. Else, it is required to prevent DLL registration issues. Also, this install is not technically a silent install. Microsoft forces a UI-based install that does not require user action, but it will be displayed to the user as a quick prompt. Setup EXE command line MSI command line
/s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\Technical Analysis.log"" qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\Technical Analysis.log"
CBT Setup Prerequisites Comments Setup EXE command line MSI command line
None Standard MSI install, no custom actions required /s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\CBT.log"" /qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\CBT.log"
DBS Upload Utility Setup Prerequisites Comments
Setup EXE command line MSI command line
None Standard MSI install, no custom actions required. In order to function properly, the end user will require IBM Client Access to be installed. Only the ODBC drivers are installed, not the fully licensed version of Client Access. /s /v"/qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\DBS Upload Utility.log"" /qn /L*v \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\DBS Upload Utility.log"
4.5 STW Upgrade Maintenance Please note that support for the 2008A (and older) releases of STW has been officially dropped. Instructions for upgrading from these unsupported releases are still provided, but are no longer officially supported or tested. They are provided as is, are not guaranteed to function properly as they are no longer tested internally.
13
4.5.1 Licensing Changes – 2009A and Older Due to changes to the licensing mechanism, beginning with the release STW 2009B, any upgrade from Cat ET 2009B or SIS 2009A will result in the immediate loss of any existing license. This change posses a significant hurdle for dealer IT automation, as any bulk upgrade will result in the need to re-license the target PCs. In addition, beginning with the STW 2009B release, both SIS and Cat ET will begin utilizing their own specific license, and no longer support sharing the license.
4.5.2 Licensing STW 2009B to STW 2010A The 2010A release of the SIS and Cat ET applications when upgrading from the 2009B release (SIS 2009B, Cat ET 2009C) will continue to utilize their respective licenses. This allows for the Dealer IT teams to implement fully automated upgrades of the SIS and Cat ET applications without concern on licensing, as each will continue to utilize the existing license.
4.5.3 Licensing STW 2009B to STW 2010A The 2010A release of the SIS and Cat ET applications when upgrading from the 2009B release (SIS 2009B, Cat ET 2009C) will continue to utilize their respective licenses. This allows for the Dealer IT teams to implement fully automated upgrades of the SIS and Cat ET applications without concern on licensing.
4.5.4 Support Applications – STW 2008A (and Older) Please see note above on support of 2008A. During the migration from the 2008A and earlier versions, a number of actions must be performed in addition to calling the standard installs. These actions should only be required on the initial upgrade away from 2007B and 2008A. Any future custom upgrade requirements should be performed within the installation, but we do recommend contacting Caterpillar if there are any concerns.
IMPORTANT: The order of events is important for these two applications. Typically the Master Installer will perform these actions, but in a remote implementation, they must be performed as part of the script. Cat ET must be uninstalled prior to running the upgrade when working with 2007B or 2008A. STW must be uninstalled after the application suite has been upgraded.
Caterpillar has provided applications that will help support the upg rade and maintenance process for the STW suite, which are located on the Knowledge Network.
14
4.5.4.1
STWMaintenance.exe
Filename Command Line Runtime Description
4.5.4.2
ETUninstall.exe
Filename Command Line Runtime Description
4.5.4.3
Maintenance Executable STWMaintenance.exe No additional parameters Microsoft .Net 2 Performs uninstalls of several applications, detects and enables any STW license on the PC, cleans filesystem.
Maintenance Executable ETUninstall.exe No additional parameters Microsoft Visual C++ 6 Performs the silent uninstall of Cat ET 2008B and older
BatchUpgrade.bat
Filename Command Line Runtime Description
Maintenance Executable BatchUpgrade.bat No additional parameters DOS Batch Script Provides an example of scripting the upgrade. This is an example, but could be used by the dealership to perform upgrades
4.5.5 Pre Upgrade 4.5.5.1
Cat ET 2008B and Older
Several complicated actions are required in order to perform a silent upgrade from Cat ET 2008B and earlier. To ease the actions required by the dealer IT staff, Caterpillar Inc. has provided an executable that will uninstall Cat ET silently, allowing the dealer IT staff to automate the upgrade. The following actions are performed by the ETUninstall.exe application. Additional Actions for Complete Upgrade: ETUninstall.exe Application Action Description Cat ET Uninstall The Cat ET 2008C release migrated the install from InstallScript to standard MSI. Prior to 2008C releases, upgrades cannot be performed in silent mode. This problem also impacts upgrading to 2008C from 2008A and below. Because of the complex nature of the Cat ET install, Caterpillar has created a utility for uninstalling the older
15
version. The utility performs the uninstall in silent mode, and returns a result code. Following the execution of ETUninstall.exe, the new release of Cat ET may be installed using standard automation methods.
IMPORTANT: If STW is not installed on the PC, the license for Cat ET is stored in the Cat ET directory. Starting with the 2009A release, Cat ET installs to a new directory by default. This could result in a loss of license. Therefore, we recommend reinstalling Cat ET to the original directory, using the Windows Installer INSTALLDIR variable.
4.5.5.2
Cat ET 2008C
Upgrading Cat ET 2008C requires no special action. During the 2008C release, the Cat ET installation tool went through a significant rewrite, allowing for silent upgrades to occur. The following actions are performed by the STWMaintenance.exe application. They must be performed after all other applications have been upgraded. 4.5.5.3
Miscellaneous
The TA application does require the Microsoft Visual C++ runtime to be installed as a prerequisite. Without this package installed, installing on Microsoft Vista may result in an install error.
Application TA
Additional Actions for Complete Upgrade Action Description Install As noted above, both a new install and upgrade of TA results in the user seeing a pre-requisite install prompt. To avoid the prompt, TA may be installed directly from the MSI, bypassing the prerequisite install steps. If this is done, we recommend either installing the VC runtime install first, or installing Cat ET (which contains the install internally).
4.5.6 Upgrade With Cat ET 2008B and older uninstalled, all applications can be upgraded using standard install instructions provided above.
4.5.7 Post Upgrade After completing the upgrade of the STW suite of applications, the old STW application should be uninstalled. The STWMaintenance.exe application will perform this function 16
in silent mode. It will also perform actions require to re-enable the license located in the STW application directory. Doing so allows Cat ET and SIS DVD to continue operating using the original Additional Actions for Complete Upgrade: STWMaintenance.exe Application Action Description SIS Web Uninstall The SIS Web (SISOLEServer) is a standalone install. It is (SIS OLE typically uninstalled via the Master Installer application. Server) While not a necessary uninstall, it should be performed to clean the system. STW Uninstall The STW Container is a standalone install. It is typically Container uninstalled via the Master Installer application. While not a necessary uninstall, it should be performed to clean the system.
FFS
Uninstall
In order to preserve the license on the PC after an upgrade, some files and registry keys will remain on the PC. Both Cat ET and SIS utilize these license files in order to allow the technician to continue operating with the original license. The FFS application is a standalone install. It is typically uninstalled via the Master Installer application. While not a necessary uninstall, it should be performed to clean the system.
4.6 Logging When implementing a custom install package, Caterpillar does request following the standard logging methods described above. This information helps assist in future trouble-shooting if an application error were to occur. We recommend using the directory used by the STW Master Installer, but this is not necessary. In order to perform logging from the command line, the path to the log file is required. Because of Windows Installer syntax requirements, the path must include 1. Preceded by a backslash 2. Enclosed in quotes 3. Double-backslashes between directories. As an example, the path might look like the following: \"C:\\Documents and Settings\\All Users\\Application Data\\Caterpillar\\Installer\\STW Launchpad.log""
17
4.7 Network Install Issues Because of a desire to increase security in Microsoft Windows, there are additional steps required in order to fully automate installs onto a PC.
4.7.1 SIS DVD – Certinstall.exe Description A known issue in the 2009A release of SIS DVD results in a prompt to the end user to verify the installation of an “unverified publisher”. This prompt will require an end user to click ‘OK’ in order to complete the install. Recommended Solution Copy the entire install to the local PC, possibly to %TEMP%\SIS\ , and launch the install from that location. Because the executable resides locally, the operating system will not force the prompt.
18
