ImageSite. Troubleshooting Guide. Version 9.x

ImageSite Troubleshooting Guide Version 9.x

Disclaimer EQUORUM MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE CONTENTS OF THIS DOCUMENT AND EXPRESSLY DISCLAIMS THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. EQUORUM RESERVES THE RIGHT TO REVISE THIS PUBLICATION WITHOUT NOTICE. UNDER NO CIRCUMSTANCES SHALL EQUORUM OR ANY OF ITS OFFICERS, DIRECTORS, EMPLOYEES OR REPRESENTATIVES BE LIABLE FOR CONSEQUENTIAL, INCIDENTAL, SPECIAL OR INDIRECT DAMAGES, LOSS OF PROFITS OR LOSS OF GOODWILL FROM OR ARISING OUT OF THE USE OF, OR INABILITY TO USE THIS DOCUMENT OR ANY PRODUCTS REFERENCED HEREIN EVEN IF EQUORUM HAS BEEN NOTIFIED OF THE LIKELIHOOD OF SUCH DAMAGES OCCURRING. THE USER IS HEREBY MADE SOLELY RESPONSIBLE FOR ASSESSING THE USER S REQUIREMENTS AND THE SUITABILITY OF THIS PRODUCT TO THE USER S NEEDS. The screen displays depicted herein are meant to be representative and not exact duplicates of those that will appear on your monitor. Trademarks ImageSite, Plot Station, and equorum are registered trademarks of equorum Corporation. Other brand or product names are trademarks or registered trademarks of their respective owners. Confidentiality This document contains confidential and proprietary information of equorum and is not to be copied, reproduced or disclosed to third parties without the prior written consent of equorum. Copyright Notice Copyright 2000-2016 equorum Corporation, Atlanta, Georgia. All rights reserved. Publication Date: February, 2016.

Table of Contents Preface... 5 About This Guide... 5 Who Should Use This Guide... 5 Contacting Technical Support... 5 Troubleshooting ImageSite... 6 Troubleshooting Resources... 7 Capturing Output for Diagnostic Purposes... 8 ImageSite Log Files... 8 Tomcat Log Files... 8 Common Installation Mistakes... 9 Running ImageSite erasticator in a Command Window... 10 To run ImageSite erasticator in a command window... 10 Troubleshooting Problems with ImageSite Operation... 11 Client Browser Hangs When Browsing for Files to Upload (Classic only)... 11 Client Browser Hangs During Upload of Very Large Documents of Any Type (Classic only) 11 Client Browser Hangs or ImageSite Viewer Toolbar is Inactive When Viewing a Document 11 Client Browser Not Downloading Signed Applet Certificates, Not Refreshing Viewed Files (Classic only)... 12 Display of Microsoft Office Documents Is Skewed... 12 Long Delay Times Accessing ImageSite... 12 Unable to Download Documents to Your Client Computer (Classic only)... 12 Unable to Print Microsoft Office Documents at the Server... 13 Unable to See the ImageSite Session Timer (Classic only)... 13 Unable to Upload CAD, PDF, PostScript, and Microsoft Office Document Types... 14 Unable to Upload Microsoft Office Documents... 15 Error Messages... 16 Initialization Error: Error getting database connection... 16 Installation Support File <filename> Could Not Be Found/Installed... 16 InstallShield Engine (ikernel.exe) Could Not Be Installed... 17 InstallShield Engine (ikernel.exe) Could Not Be Launched... 17 Internal Error 2349... 17 Servlet Initialization Failed... 17 Appendix A Updating Java/Tomcat... 18 Updating Java... 18 Updating Tomcat... 18

4 Appendix B Enabling ImageSite for Mobile Devices... 20

5 Preface About This Guide This is a troubleshooting guide for ImageSite 9.x. Who Should Use This Guide This guide should be used by ImageSite site administrators. It requires familiarity with Microsoft Windows 2008+, Microsoft SQL Server (or Express) 2008+, or Oracle (10g, or 11g). You should also be familiar with basic software installation practices in these environments. Contacting Technical Support You can reach equorum Technical Support in the following ways: Phone: 404-497-8155 Monday Friday 8:30 a.m. - 5:30 p.m. EST FAX: 404-497-8101 e-mail: Web: support@equorum.com download from http://www.equorum.com/servicesupport/have-a-question/ When contacting technical support, please have the following information ready to give to the support analyst: Your name, company name, email address, phone number, and customer ID number The ImageSite or Plot Station version number A brief description of the problem Any error code(s) and/or message(s) you encountered and the order in which they appeared ImageSite logs (from both /tomcat/logs and /ims/logs) You ImageSite server s system environment variables, found by running SET from a command prompt. Your /ims/conf/ims_config.properties file. A connection to your database. For SQL Server, a configured SQL Server Management Studio. For Oracle, either SQLPlus or SQL Developer (preferred). Be ready to send logs, files, and SQL output to support@equorum.com

6 Troubleshooting ImageSite This section provides information on preparing for troubleshooting and on troubleshooting specific errors that may occur when running ImageSite after installation and setup. Troubleshooting Resources Capturing Output for Diagnostic Purposes Common Installation Mistakes Troubleshooting Problems with ImageSite Operation Error Messages

7 Troubleshooting Resources The first step for effective troubleshooting is to have the necessary tools and information available when you need them. Keep an up-todate library of CD/DVDs for unexpected software issues such as Windows OS service packs and current Internet Explorer browsers. For ImageSite, consider maintaining a library of the following items: Windows 2008/2012 Windows Server Service Packs Internet Explorer 9.0+ Microsoft SQL Server or Oracle Server equorum Product DVD You should also maintain a library of documentation for your web server and other products, either printed or on CD. At a minimum, you should know what is available online and how to find the information. In addition, the following helpful items are installed with ImageSite: ImageSite Hardware and Software Guide (in c:\ims\docs by default). ImageSite Installation Guide (c:\ims\docs) ImageSite Implementation Guide (C:\ims\docs) Any Upgrade guides you used. SQL scripts for testing ImageSite database integrity (C:\ims\db-scripts by default. These scripts should be used only by experienced ImageSite analysts.)

8 Troubleshooting ImageSite Capturing Output for Diagnostic Purposes ImageSite requires that several components be properly installed and configured. Each of these components creates log files that can be useful for diagnosing problems that might occur. ImageSite also maintains logs related to image processing. ImageSite Log Files The following ImageSite log files are helpful for diagnosing problems: Default Path on the Web Server C:\ims\logs Log File Name rasterdemon.log jobprep.log UploadLog.CSV BulkAcquireAndQBulk.log BatchIndexing.log Tomcat Log Files The following automatically generated log files are helpful for diagnosing problems with the Apache/Tomcat software, as well as ImageSite: Default Path on the Web Server C:\tomcat\logs Log File Name, similar to: Tomcat8-stderr.*.log Tomcat8-stdout.*.log localhost*.log

9 Common Installation Mistakes Installation of ImageSite is an involved process, and mistakes do occur. Some of the most common include the following: Error Type Database connection Typing errors Description and Tips ODBC database connection errors can be caused by DSN setup problems, a bad name, or a wrong driver. Always test the connection. In particular, look for the following: The C:\ims\conf\IMS_CONFIG.PROPERTIES file must be correctly modified to include the correct database server name in the JDBC connection string. The C:\ims\web\WEB-INF\web.xml file must be correctly modified to point to the correct path for the ImageSite files, if you did not install to the default C:\ims location. If you are running a 64 bit system, do not run the ODBC manager from Administrative Tools. Instead, run the odbcad32.exe located in the C:\WINDOWS\SysWOW64 directory. Typing errors introduced while editing configuration files are very hard to find and fix once they occur. Fortunately, such errors are easily avoided. Observe the following rule: Double-check placement and syntax, especially if you typed an entry in a file. Most typing errors are in the following files: C:\ims\web\WEB-INF\web.xml C:\ims\conf\IMS_CONFIG.PROPERTIES

10 Troubleshooting ImageSite Running ImageSite erasticator in a Command Window If a problem occurs with uploading file types other than CALS, JPG, and TIF, errors can be found in the Rasterdemon.log file. As an alternative to viewing the log file after each operation, you can run the ImageSite erasticator service in a command window in debug mode. Information displayed for the service running in debug mode is more detailed than information captured in the log file. Note: For step-by-step instructions on what to do if uploading of some files types to ImageSite fails, refer to Unable to Upload CAD, PDF, PostScript, and Microsoft Office Document Types on page 12. To run ImageSite erasticator in a command window 1 Stop the ImageSite erasticator service. 2 Open a command window as an Administrator. 3 Change directory to the C:\ims\native\process folder. 4 Enter the following command: Rasterdemon.exe d v The ImageSite erasticator debug-mode window is displayed. 5 Upload the problem file again and observe the rasterdemon window for any errors or problems.

11 Troubleshooting Problems with ImageSite Operation After installing ImageSite and accessing the site, you may encounter the following problems during ImageSite operation. Client Browser Hangs When Browsing for Files to Upload (Classic only) The Internet Explorer browser on the client computer may hang while browsing for files to upload. When this happens, the JVM will log a security failure attempting to access the local file system. The problem appears to be related to security changes in some JVMs. You can rightclick on the Java coffee cup icon on the task bar and open the Java Console to view this log. Take the following steps on the client computer to install the latest Java JRE: 1 Determine which JRE version is installed on the client computer: From your Windows control panel, open the Java Plug-in Control Panel. Choose the Advanced tab and verify that a JRE Java Plug-in is selected. 2 Do the following to install a newer JRE version: From your Windows control panel > Add/Remove Programs dialog, uninstall all Java Runtime Environment entries. Visit Java.com and install the latest version of the JRE. If that version gives you any problems, contact equorum support. Client Browser Hangs During Upload of Very Large Documents of Any Type (Classic only) This problem can occur when uploading very large documents (15 Mb or more) The JAVA Console reports error message "java.lang.outofmemoryerror: Java heap space." To correct the problem: Upgrade to the latest version of ImageSite, if you have not already done so. Install the latest Java JRE from java.com. Client Browser Hangs or ImageSite Viewer Toolbar is Inactive When Viewing a Document There are reports of interference with normal operations of various web-based applications when Google desktop search engine and

12 Troubleshooting ImageSite Google e-mail notifier are installed. In ImageSite, they can cause long viewer toolbar delays and possible browser hang. Take the following steps to correct the problem: Uninstall Google desktop search engine and Google e-mail notifier on any computer that will be used to access ImageSite. Client Browser Not Downloading Signed Applet Certificates, Not Refreshing Viewed Files (Classic only) These problems can occur when the client is accessing the ImageSite server via a proxy server. 1 Select Start > Settings > Control Panel > Java. The Java Control Panel dialog is displayed. 2 On the General tab, do the following: In the Network Settings area, click Network Settings. Then select the Use Proxy Server option. In the Temporary Internet Files area, click Settings. Then click View Applets and uncheck the Enable Caching control. Display of Microsoft Office Documents Is Skewed Microsoft Office document image displays may be skewed if the display adapter on the web server is not set to a value greater than 256 colors. 1 Select Start > Settings > Control Panel > Display. The Display Properties dialog is displayed. 2 On the Settings tab, choose a Color Palette value that is greater than 256 colors. equorum recommends High Color (16 bit). 3 Click OK. Long Delay Times Accessing ImageSite It may be helpful to add the mapped machine name of the ImageSite web server into the hosts file on the client that is experiencing the delay. The hosts file resides in the Windows\system32\drivers\etc directory. In addition, it may be helpful to include the fully qualified domain name (FQDN) when accessing ImageSite. Unable to Download Documents to Your Client Computer (Classic only) Document download to your client computer may fail with various types of error messages or java null pointer. Take the same steps as for the Client Browser Hangs When Browsing for Files to Upload problem.

13 Unable to Print Microsoft Office Documents at the Server Microsoft Office documents will fail to print at the server location if the display adapter on both the web server and the Plot Station Server is not set to a value greater than 256 colors. Take the following steps on both the web server and the Plot Station server, if ImageSite and Plot Station are installed on separate computers. 1 Select Start > Settings > Control Panel > Display. The Display Properties dialog is displayed. 2 On the Settings tab, choose a Color Palette value that is greater than 256 colors. equorum recommends High Color (16 bit). 3 Click OK. 4 Also make sure the Windows Print Spooler service is running and set to Automatic. 5 For Windows 2008, make sure you have a valid ProfileImagePath defined in the registry: Changing the ProfileImagePath registry entry to support Microsoft Office Automation when running as a service. If you are uploading Microsoft Office documents to ImageSite running on a Windows 2008 Server perform the following steps: Start REGEDIT Navigate to HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\ProfileList\S-1-5-18\ProfileImagePath and make a backup of its value. Within the ProfileList registry hive, locate a valid desktop user profile (it should start with S-1-5-21-[xxxx]). Copy the value for its ProfileImagePath and overwrite the one assigned to the Local System profile. Restart your system. Unable to See the ImageSite Session Timer (Classic only) The ImageSite session timer is an applet that is displayed in the upper left corner of the ImageSite application after login. The functionality of this and all other ImageSite applets will be lost to the end user if ImageSite is launched from a computer that does not have a java virtual machine plug-in installed. To correct the problem: Install an Oracle Java virtual machine plug-in, which is required by ImageSite. equorum recommends using the latest Java JRE, available from java.com.

14 Troubleshooting ImageSite Unable to Upload CAD, PDF, PostScript, and Microsoft Office Document Types For CAD, PDF, PostScript, and Microsoft Office file types, processing and uploading to the ImageSite server are handled by the ImageSite erasticator service. Processing and uploading will fail if the ImageSite erasticator service cannot access the database properly. 1. Open the rasterdemon.log file that is written to the ImageSite install directory (C:\ims, by default). 2. If the rasterdemon.log file contains ADO error messages, do the following: Stop and restart the ImageSite erasticator service. Upload CAD, PDF, PostScript, or Microsoft Office files to ImageSite. If the upload fails again, re-examine the rasterdemon.log file. If the log file still contains ADO error messages, go to Step 3. 3. Examine your system DSN for errors in setup. After making any necessary changes, do the following: Stop and restart the ImageSite erasticator service. Reupload CAD, PDF, PostScript, or Microsoft Office files to ImageSite.

15 Unable to Upload Microsoft Office Documents This problem occurs if Microsoft Office is not installed on the ImageSite web server, if the ImageCollectorEMF printer was not properly installed during ImageSite installation, or if the user assigned to the ImageSite erasticator service does not have the appropriate permissions for Microsoft Office automation. Note: Microsoft Office must be installed on the web server if ImageSite will be used to upload and view Microsoft Office files. Microsoft Office 2003 and newer versions are supported. Note: For Windows 2008+, make sure you have defined a ProfileImagePath as described above under the section Unable to Print Microsoft Office Documents at the Server. 1. Verify that MS Office is installed on the web server. If not: Install Microsoft Office on the web server. Reboot the web server. 2. Verify that the Windows Print Spooler service is running and set to Automatic. 3. Verify that the ImageCollectorEMF printer is included in the list of Windows printers on the web server. If not: Uninstall and reinstall ImageSite. Reboot the web server. 4. Verify that the user assigned to the ImageSite erasticator service has the appropriate permissions for Microsoft Office automation. For Windows 2008, make sure you have a valid ProfileImagePath defined in the registry: To set the ProfileImagePath: a. Start REGEDIT b. Navigate to HKEY_LOCAL_MACHINE\Software\Microsoft\Windows NT\CurrentVersion\ProfileList\S-1-5-18\ProfileImagePath and make a backup of its value. c. Within the ProfileList registry hive, locate a valid desktop user profile (it should start with S-1-5-21-[xxxx]). Copy the value for its ProfileImagePath and overwrite the one assigned to the Local System profile. d. Restart your system. 5. Try to upload MS Office files again.

16 Troubleshooting ImageSite Error Messages Three categories of error messages are presented here: Errors that may occur during installation Errors that may occur when trying to access the web server Errors that may occur when trying to access the ImageSite site Initialization Error: Error getting database connection This error message replaces the ImageSite login page if a database disconnection occurs. A disconnection can occur periodically if either ImageSite or SQL Server database is running on a Windows computer with the network card configured to "Allow this computer to turn off this device to save power." To disable this control, do the following on the ImageSite and/or SQL Server computer: 1 Open the Windows Control Panel > Network and Sharing. 2 Click the appropriate Network Connection and then select Properties. 3 Under the adapter name, click Configure. 4 Click the Power Management tab. The Power Management dialog is displayed. 5 Uncheck the control to Allow this computer to Turn off this device to save power. Installation Support File <filename> Could Not Be Found/Installed This message may be generated by InstallShield immediately after ImageSite setup.exe is started, and InstallShield will fail to start the ImageSite installation program. The InstallShield web site knowledge base suggests the following action to correct the problem: On the web server, delete the contents of the \Program Files\Install Shield Information directory before installing.

17 InstallShield Engine (ikernel.exe) Could Not Be Installed OR InstallShield Engine (ikernel.exe) Could Not Be Launched These errors may be displayed while uninstalling ImageSite if the logged on user does not have appropriate permissions for the uninstall. Take the following steps to verify that the user has the appropriate permissions: Log on as the same user who installed ImageSite. or In the Start > Run dialog box, enter dcomcnfg to display the Distributed COM Configuration Properties dialog box. On the Default Security tab, do the following : In the Default Access Permissions area, click the Edit Default button. Add the user who is to perform the ImageSite uninstall and click Apply. In the Default Launch Permissions area, click the Edit Default button. Add the user who is to perform the ImageSite uninstall and click Apply. Internal Error 2349 This error may be displayed during ImageSIte installation, or InstallShield may simply hang, if you are running anti-virus protection on the web server during the installation process. To correct the error, do the following: 1 Cancel the ImageSite installation process. 2 Disable the anti-virus protection. 3 Re-start the ImageSite installation. 4 Re-start the anti-virus protection when ImageSite installation is complete. Servlet Initialization Failed This error may be displayed in the browser if the Tomcat configuration file was incorrectly edited during installation. To correct the error, do the following: 1 Verify that the C:\ims\WEB-INF\web.xml file exists. 2 Verify that the paths in the C:\ims\WEB-INF\web.xml file are correct if ImageSite or Tomcat was installed to a directory other than the default.

18 Appendix A Updating Java/Tomcat This section provides information on updating Java and/or Tomcat on your ImageSite server without updating ImageSite itself. Updating Java When updating Java, equorum recommends that you first uninstall any old versions of Java, then install the new version, rather than using the in-place Java upgrade Tool. After you install the new Java version, you will need to configure Tomcat to point to the new installation location of jvm.dll. To do so, run the Configure Tomcat tool from the Start Menu, then click the Java tab, and navigate to the location of jvm.dll, typically in Program Files\Java\jre7\bin\client\jvm.dll (or Program Files (x86) if using a 64-bit Operating System. Start the newly configured Tomcat service and check the Tomcat logs for any errors. If Tomcat is configured properly, you should see something like this at the beginning of the log: ImageSite.init() : JRE Version detected = x.x.xx (your new version) Otherwise, the Tomcat service may fail to start. Updating Tomcat Whenever you update or make changes to the Tomcat service, it is important to do the following: 1. Note the login account used for the Apache Tomcat service. 2. Stop the Tomcat and ImageSite erasticator services. 3. Back up the entire \tomcat directory. You will need any custom configuration information contained within these files. Specifically, the files you will need and what they contain are: \tomcat\webapps\root\favicon.ico file (the browser icon used for ImageSite) \tomcat\conf\catalina.properties file (custom Tomcat modules) \tomcat\conf\server.xml file (port configuration) \tomcat\conf\web.xml file

19 Any keystores used for SSL. (secure socket layer, or https). If you use SSL, to find your encryption key information, look in the server.xml file for lines similar to this: SSLEnabled="true" keystorefile="c:\tomcat\tomcat.keystore" If the keystorefile points to a location outside of the Tomcat directory, make sure you can access it, back up the file indicated and make a note of the password indicated by keystorepass="mypassword". Once you back up Tomcat: 1. Uninstall the old Tomcat, delete all the files. 2. Install the new Tomcat version. 3. Reinstall ImageSite. 4. Copy in the keystore file, if you have one). 5. Apply any ImageSite patches. 6. Launch Tomcat; check the logs for errors.

20 Appendix B Enabling ImageSite for Mobile Devices An ImageSite site administrator can enable the Mobile device application by adding an entry to the system defaults table. To enable the Mobile application, log in as a site administrator and go to the Classic interface. Then: 1. Click the System button on the left: 2. Click the System Defaults Table link: 3. Enter the following item, as shown (this is case-sensitive), and click the Add button: System, EnableMobile, 1 4. Enter this system default item as well: System, DetectMobile, 1 5. Log out. The Log In screen should now have the Mobile option. 6. An actual mobile device should be detected and default to the Mobile application UI Selection.