GUIDE Workshare Troubleshooting Guide
Table of Contents Understanding Troubleshooting...3 System Understanding... 3 Strategic Understanding... 3 Procedural Understanding... 4 Troubleshooting Strategy...5 Recording the Symptoms... 5 Expected Behavior...5 Symptoms and Details of an Issue...5 Recreating the Problem... 5 Isolating Possible Causes... 6 Devising and Implementing a Plan... 6 Testing... 7 Confirming... 7 Documenting... 7 Troubleshooting Checklists...8 Checklists... 8 Initial s...8 Installation Issues...9 Licensing Issues...10 Issue Sending Email (Protect-Related)...12 Issues Sending an Email (Not Protect-Related)...13 Issue Comparing Documents...14 Issues Saving a Redline...15 Issues with PDF Creation...16 OCR Server Issues...17 Protect Server Issues...19 Citrix Issues...20 Lotus Notes Issues...21 2
Understanding Troubleshooting Troubleshooting software is the logical, systematic process of searching for and eliminating the source of a problem. The two most important and fundamental troubleshooting concepts are replication and isolation. Replication involves recreating the exact problem, including both the issue itself and a procedure or series of steps that can reliably induce the reported issue to occur. Replication is important for two reasons: To confirm a reported issue is actually an issue and not a product of user error, a random and nonrepeatable system anomaly, or etc. To provide a way by which a resolution can be confirmed. If an issue cannot be replicated, determining whether or not a proposed solution resolves the issue becomes problematic. Isolation involves identifying and separating the factors necessary to reproduce an issue from the ones that are superfluous. Studies on the factors contributing to efficient and effective troubleshooting show that the primary determinant is how well the individual performing the troubleshooting understands the system they are troubleshooting. Overall understanding can be grouped into three categories: system, strategic, and procedural. The sections following describe the characteristics and behavior of inexperienced and experienced troubleshooters in relation to these categories. System Understanding System understanding consists of practical functionality ( how it works ) knowledge about the components of the application, knowledge of inputs and outputs to the components of the application, and understanding of the application topology that is, how all the component of the application connect all at a level of detail necessary to accomplish required tasks. Inexperienced troubleshooters tend not to evidence appropriate mental models of the software application sufficient to direct troubleshooting behavior, while experienced troubleshooters evidence a fuller understanding of how individual components operate within any given software application. Note that this understanding does not require an understanding of the inner workings of these same components you don t need to know the details of how an MS Outlook client connects to its Exchange server to be able to tell whether or not the server is connected. Experienced troubleshooters also demonstrate a principled sense of software system functioning beyond the specifics of any particular application, and organized their knowledge hierarchically according to the functional boundaries of the system. They understand the individual and shared characteristics of MS Office, DMS, and other integrated software systems. An important consequence of this type of understanding is that, even in the absence of training specific to a particular application or software environment (a completely pre-specified model of a system), experienced troubleshooters can nevertheless still construct a mental model from which to proceed in their troubleshooting efforts. Strategic Understanding Inexperienced troubleshooters tend not to employ effective troubleshooting strategies. Specifically, they demonstrate little ability to perform actions that allow them to draw inferences about the problem from the behavior of the system. 3
In many cases, one of the only strategies employed by inexperienced troubleshooters is to follow designated procedures in technical materials (Solutions or CRs), even when it is not clear that the symptoms of an issue match the conditions described within the Solution or CR. While Solutions and CRs contain important and useful information, inexperienced troubleshooters often fail to understand this information or how it is generally constrained to a particular, specific problem space. Even in those cases where inexperienced troubleshooters exhibit some system understanding, they frequently use a serial elimination strategy, wherein single components are examined and tested, one-by-one, typically in the order a particular failing process calls or references them. This strategy is generally very inefficient. Experienced troubleshooters try to use space-splitting strategies, isolating problems to a subsystem by using relatively few procedures, each one of which eliminates large sections of the problem area. When experienced troubleshooters consult Solutions and CRs, they do so as a reference to check whether they may be overlooking a particular, lesser-known problem source, or to see if the issue has been reported and addressed previously. Furthermore, any information contained within the Solution or CR is first checked against the actual, observed issue and environment to ensure it is relevant. Procedural Understanding An application can be considered as a system of components. At the most basic these components are files (executables, dlls, etc.), but specific groupings of particular files can also be considered as their own component. Every component of an application can be acted upon through a variety of procedures that provide information about some subset of the application. Information about some types of components can only be gained by removing and replacing them. Other can be acted upon by inspecting inputs and outputs (MS Word file types, for example) and by changing states (enabling or disabling them). Some actions, including most removing and replacing procedures, provide limited information about larger pieces of the problem area under certain states of the system model. Inexperienced troubleshooters generally limit themselves to removing and replacing actions installing and uninstalling software. They often fail to spontaneously acquire or use the information that can be provided by standard tests and indicators. Experienced troubleshooters, on the other hand, use standard tests and indicators to help narrow the solution space, and tend to view installing and uninstalling an application as a last resort as it generally provides no information on why an issue occurred, which means there is therefore no way to tell if, when, or under what circumstances the same issue will recur. 4
Troubleshooting Strategy The following seven-step model provides a reliable and systematic way to troubleshoot an issue: Recording the symptoms of the problem Recreating the problem Isolating possible causes Devising and Implementing a plan to solve one of the possible causes Testing to confirm the problem has been solved Confirming the problem has been solved Documenting the problem and solution Recording the Symptoms Efficient, effective troubleshooting starts with a clear understanding of both of the following: the expected behavior of the application the symptoms and details of the reported issue Expected Behavior Knowing what the results of a particular series of steps should be is essential to recognizing when the results are incorrect. Symptoms and Details of an Issue If there is an error message, recording the error message might seem like an obvious step. Obvious or not, recording the exact and complete text and the series of steps that led to the error can be vital to troubleshooting an issue. Many error messages appear very similar but have subtle differences, and can result from completely different causes. Consider the report of an Object reference error. The actual message might refer to an Object reference not found error, an Object reference not set error, a Cannot access a property or method of a null object reference error, etc. Each of these errors result from some different cause, each would have a different solution, and without knowing which error is actually being seen, finding the correct solution is significantly more difficult. Recreating the Problem One of the most time-consuming steps in troubleshooting is finding a procedure or series of steps that can reliably induce the reported issue to occur. This is a very important step. If an issue cannot be reproduced repeatedly though a specific series of steps, isolating the cause is difficult, but even more difficult is confirming that a particular solution resolves the issue if you don t know exactly when a problem happens, how can you tell if it has stopped happening? The following are questions that can be asked of a user that can assist when attempting to determine how to recreate an issue consistently: 5
When and how did you notice the problem? Was anything being done differently that made you notice the problem? Is the process that is causing the problem a new procedure, or has it worked successfully before? If this process worked before, what has changed? o Note that this can be any type of change made to the system, ranging from adding new hardware or software, to configuration changes that may have made to existing software. When you noticed the first symptom of this problem, were there other symptoms or problems occurring around that time? Does the same problem occur elsewhere? Is only one machine experiencing the problem or are multiple machines experiencing the same problem? Are there any messages generated that indicate there is a problem? What else do you see that tells you there is a problem? How often does the problem occur? Isolating Possible Causes Once an issue can be consistently replicated, the next step is to narrow down the possible causes by identifying and eliminating factors that have nothing to do with the problem. This is also known as localizing the extent of the problem, or defining the problem domain. To do this, narrow the scope of the problem by eliminating sub-areas of the problem space that are not related to the problem. For example, if a PDF conversion error occurs when a document attached to an email message is sent and converted to PDF, test to see if the same issue happens when simply converting to PDF. If it does, you ve eliminated the entire email system and process from the list of possible causes and can exclude it from any further troubleshooting of this issue. By using a process of elimination like this, you can simplify your troubleshooting by avoiding spending time investigating components, processes, and other areas that have nothing to do with the actual issue. Once all extraneous factors have been eliminated, the actual possible causes of the issue remain. Devising and Implementing a Plan Based on the possible causes isolated in the previous step, devise a plan to solve the problem. Keep in mind that the solution might not be successful, and always make sure returning the system to the base state is possible. Always make a copy of dll files before replacing, create and save configuration files before making changes, export registry keys before altering, etc., in case the devised solution does not resolve the issue and a rollback is therefore necessary. Document any changes made so that a complete rollback of the system becomes necessary. Efficient, effective troubleshooting starts with a clear understanding of both the expected behavior and of the symptoms and details of the reported issue, and needlessly complications can be prevented by always restarting at the base state that is, the state the system was in before you started troubleshooting. 6
Testing Testing consists of confirming that a problem has actually been solved and checking to make sure the solution does not inadvertently cause some other process to stop functioning. If you can repeatedly reproduce an issue by following a specific series of steps, the first part of testing is trivial, consisting entirely of checking whether or not following the specific series of steps that resulted in an issue still results in the issue. The second part of testing takes a little more effort, but can usually be accomplished in short order by performing standard tasks: create a redline, send as an email with attachment to an external address, convert the redline to PDF, etc. Confirming Confirm with the person who reported the issue that the problem has been solved. This step is both the simplest and the most important. It doesn t matter how much time and effort has been put into resolving an issue if the person who reported an issue doesn t know it s been fixed. Documenting Often overlooked, documentation is a vital part of the troubleshooting process for the following two reasons: To save the knowledge gained through the troubleshooting process so the same issue reported in the future can be resolved quickly and efficiently. Consider a problem that took two other people a total of 6 hours to solve. Without documenting what they did to finally solve the problem, the next time this same issue arises, someone else might need to spend another 6 hours finding the same solution. To document how the system in which the issue was observed was changed in case a side-effect of a solution arises. While the second part of the testing phase can help avoid these issues, testing every function on a computer affected by a solution can be impractical, and documenting what was done provides a way to understand the changes made and how to undo them if necessary or desirable. 7
Troubleshooting Checklists Checklists The following troubleshooting checklists are intended to help in localizing the extent of the problem, or pinpoint the where and when an issue is occurring. Note that not all questions are relevant to all issues. Initial s These questions should be asked and answered before any other troubleshooting takes place, and the answers they provide can often significantly narrow down the problem domain. (Note: As these questions should be asked when troubleshooting any issue, as a reminder they will be the first questions listed in each of the remaining checklists.) from a single action (e.g. clicking the Compare button in MS Word), what is the first issue or a. Software was not installed. b. Application was installed and running correctly for some period of time. Workshare upgraded and now issue occurs. c. Application was installed and running correctly for some period of time. Some other software was installed or upgraded and now the issue occurs. d. Application was installed and running correctly for some period of time. No known change to environment. This happens because errors that occur after the initial issue are often caused by the initial issue in that whatever processes still continue after the initial error expect certain parameters, values, etc. to run properly. A failure at an early step in a process can likely not pass on whatever is the expected by subsequent process, thus causing the subsequent errors. Therefore, resolving the first issue can result in subsequent ones never occurring. If there is an error message, recording the exact and complete text can be vitally important, as even slightly different error messages can result from Examples: - If no Workshare software was ever installed on a computer now having a Workshare-related issue, it could be that the installation did not complete successfully. - If a previous version of Workshare software was installed on a computer, and that software was replaced with a new version, it could be that the old version was not uninstalled completely or correctly, or that an old configuration or.runtimepolicy file has been carried over. 8
Installation Issues s to ask when installations issues occur. Does the user have full rights to necessary directories and registry keys? Was there a Workshare application already or previously installed? Have all prerequisites been installed correctly? Insufficient rights will prevent the installation of any software. Depending on which rights are missing, results can be either a complete failure to install or a partial installation with subsequent incorrect behaviors. If a previous version of a Workshare application was installed on a computer, and that software was replaced with a new version, it could be that the old version was not uninstalled completely or correctly, or that an old configuration or.runtimepolicy file has been carried over. If a different Workshare application was installed, it should be confirmed that the two applications are compatible. Missing or incorrectly installed prerequisites will either prevent the application from installing or will result in incorrect or unexpected behavior of an installed application. 9
Licensing Issues s to ask when licensing issues occur. Is the license number valid, current, and not over-deployed? Licenses follow a specific format: four groups of three numerals, with each grouping separated by a hyphen: xxx-xxx-xxx-xxx Licenses have expiration dates, An expired license, or a number that has been used to license more computers than was Is the following error message observed? Manage Changes is only available in Workshare Professional. To learn more about this functionality or upgrade, click the Upgrade button below. Is the following error message observed? Invalid Authorization Code Is the following error message observed? Your License has expired Is the following error message observed? PDF Comparison is only available in Workshare Professional Can the computer connect to the license server? Can you Release and Get a license? Are there components listed in Workshare > Workshare Configuration Manager > Registration > Features? This error can result from an inability to connect to the License Server. Open a web browser and attempt to connect to http://las.workshare.com/checkconnection This error can result from an invalid license code, a license code that has been input incorrectly, a corrupted license file, or incorrect licensing information in an ini or xml file. This error can result from a missing or corrupted license file. This error generally occurs due to a missing or corrupted license file. If a connection to http://las.workshare.com/checkconnection cannot be made or a ping of las.workshare.com fails, something (usually a client firewall or proxy server) is blocking access. Without access, a computer cannot be licensed without having a license file provided. Inability to Release and Get a license results from a lack of permissions to write to the Modules directory or an inability to connect to the License Server. If there are no components listed, a license code valid for the product has not been provided. 10
Do the components listed in Workshare > Workshare Configuration Manager > Registration > Features show the correct license number and expiration date? Does the application show correctly licensed on the Workshare panel in MS Word? The license number and expiration date shown are obtained from the license file; incorrect values imply incorrect information in the license file, problems reading the license file due to permissions or damaged to the license file, or conflicting license files and/or license codes in an ini or xml file. The Workshare panel in MS Word should show both the correct license code and the name of the organization associated with the license. 11
Issue Sending Email (Protect-Related) Note: All tests should be performed using the Sample Original Document.doc from a local drive to eliminate network or DMS issues as possible causes. If the issue is not observed with the Sample Original Document.doc: If only observed with other local documents but not the Sample Original Document.doc, see the section on Document Specific Issues. If only observed with documents on a network, see the section on Network Issues. If only observed with documents on a DMS, see the section on DMS Issues. If the issue is observed using the Sample Original Document.doc from a local drive: What happens if all Workshare add-ins within MS Outlook are disabled and an email with attachment is sent to an external address? What happens if all add-ins are disabled in MS Outlook except the Workshare add-in and an email with attachment is sent to an external address? If an issue occurs when the sending an email though MS Outlook and the Workshare add-ins within Outlook have been disabled, it is unlikely that the cause of the issue is Workshare. Test the same scenario on a computer as identical as possible that has never had Workshare installed. If the issue does not occur, check for a conflict with another Outlook add-in by adding the other add-ins back, one by one, until the issue is again observed. Once found, disable all add-ins except the last one added and the Workshare add-ins to confirm the conflict. 12
Issues Sending an Email (Not Protect-Related) s to ask when issues sending an email without Protect installed occur. 13
Issue Comparing Documents s to ask when issues comparing documents occur. Does this issue happen when documents are compared directly through the Workshare Compare application, through the MS Word interface, or both? Does the issue occur when comparing: If the issue occurs only when comparing documents through the MS Word interface, the implication is that the issue involves MS Word integration. a. Documents from the DMS? If the issue occurs only with documents from the DMS, the issue might be related to DMS configuration settings and / or integration with the DMS only. b. Local documents? If the issue occurs with local documents in addition to documents from the DMS, there is no need to troubleshoot the DMS issues until local documents can be compared successfully. c. The Workshare sample documents (Sample Original Document.doc and Sample Modified Document.doc)? If it does not, can the issue be reproduced with the client s documents on your computer? d. Does the issue only occur when comparing certain file types (.DOC /.DOCX /.RTF)? Does the issue occur with binary document comparison on? Off? If the comparison fails with the Workshare Sample documents, the implication is that there is an issue specific either to the machine or the user profile. If, however, a comparison of the Workshare Sample documents does not fail, the issue is likely specific to the client s documents. This can be confirmed by reproducing the issue with the client s documents outside the client s environment. The issue may be related to a Microsoft file-type converter. This can occur if the documents are based off older versions of Word or WordPerfect. Copy the contents of the documents to a new container may resolve the issue. 14
Issues Saving a Redline s to ask when issues trying to save a successful comparison occur. 15
Issues with PDF Creation s to ask when issues creating a PDF occur. Is the Workshare PDF Printer installed properly? What is the result of running C:\Program Files\Workshare\Modules\Install.exe? If you use test documents that were not created by the client, do you see the same issue? Does the issue happen with local documents, documents on DMS, or both? If you open a document where the issue is observed and use Workshare s Convert to PDF toolbar button or ribbon, is the same issue observed? Are there other PDF printers installed on the computer? Does the client have any kind of print tracking software? (Examples: LaserTrak, Copitrak) Open the Properties of the Workshare PDF Publisher. Is the driver Amyuni Document Converter 400? Is the port LPT1? Running C:\Program Files\Workshare\Modules\Install.exe reinstalls the Amyuni PDF printer driver, and errors resulting from running this executable can help isolate the cause of PDF creation issues. If the issue occurs only with documents created by the client, isolating the elements in the client s document If the issue occurs with local documents in addition to documents from the DMS, there is no need to troubleshoot the DMS issues until local documents can be converted to PDF successfully. If the comparison fails with the Workshare Sample documents, the implication is that there is an issue specific either to the machine or the user profile. If, however, a comparison of the Workshare Sample documents does not fail, the issue is likely specific to the client s documents. This can be confirmed by reproducing the issue with the client s documents outside the client s environment. Possible printer driver conflict. Print tracking software can intercept our PDF printing process. If this is case, adding an exception for our PDF publisher will be necessary. Change the port to null. 16
OCR Server Issues s to ask when OCR Server issues occur. Can you compare Word documents located on the Desktop? Can you compare PDF documents (located on the Desktop) that do not require the OCR server? Does the OCR process work from another computer connecting to the same OCR server? Open the Workshare Configuration Manager, scroll down to OCR, make sure Advanced PDF is selected, then select Configure. Is the address to the OCR server is correct? If the address to the OCR server is correct, select Connect. Is connection successful? Log onto the Terminal Server that houses ABBYY Recognition Server and launch the Remote Administration Console (Start/All Programs/ABBYY Recognition Server 2.0). Browse to Jobs/Job Log and check to see if the output for the documents compared shows as successful. On the terminal server, browse to the Documents and Settings\All Users\Application Data\ABBYY Recognition Server 2.0\Default Workflow\ folder. Are there jobs in the Output folder? In the Exception folder? Until Word documents on the Desktop can be compared, there is need to troubleshoot the server or the connection to the server. If documents can be compared on the Desktop, this points to the cause of the issue being either the server or connection between the client and the server. If the OCR process works from another computer, it is unlikely that the server is cause the issue. If the address to the OCR server is incorrect, the application will be unable to find the OCR server. If a 404 error is returned, check on the server that ASP.NET v2.0.5.0727 is correctly configured as follows: 1. Go to IIS Manager. 2. Click the Web Service Extensions folder. 3. Look for ASP.NET v2.0.5.0727 and check that the status is Allowed. 4. If status is Prohibited, click Allow to enable the extension. 5. Re-test the URL: http://localhost/recognitionws/rssoapservice.asmx If the output for the documents compared shows as successful, the server considers the OCR process to have been successfully completed. Once processed, documents should appear in the Output folder if the OCR process is successful. If a document cannot be processed (due to image file corruption or invalid format) the image will be placed into the Exception folder. 17
On the terminal server, browse to the Documents and Settings\All Users\Application Data\ABBYY Recognition Server 2.0\Default Workflow\ folder. If you copy a scanned PDF into the Input folder, do the results show up in the Output or the Exception folder? When a scanned PDF is copied into the Input folder, the results should appear in the Output folder. If the PDF cannot be processed (due to image file corruption or invalid format) the image will be placed into the Exception folder. If the PDF stays in the Input folder, it is likely that either the OCR service is not running or the server is not configured with the correct path to the processing folders. 18
Protect Server Issues s to ask when Protect Server issues occur. 19
Citrix Issues s to ask when issues on a Citrix server occur. Has the license been TS enabled? Does the issue happen when logged directly into the server? Does the issue occur on all workstations? Does the issue occur for all users on a particular workstation? In order to function properly in Citrix, the product license must be set to allow its use on a Terminal Server. An issue that doesn t occur when logged into the server but does occur when logged into a workstation implies a problem with permissions or with profile information. If the issue occurs for all users on all workstations in a given environment, the issue is likely to be related to the configuration of the application on the server, or an issue with the server itself. If the issue happens for just one or some users, not all, the issue is likely to be related to the user-specific / profile issues. Examples: inadequate permissions, or problematic local xml files. 20
Lotus Notes Issues s to ask when issues involving Lotus Notes occur. Does the issue occur for all users on a particular computer? Does the issue occur on all computers? Can an email be sent from the Desktop through right-click > Send To > Mail Recipient? Does the environment include multiple Notes.ini files? Does the local Notes.ini file contain a line starting with EXTMGR_ADDINS= that references WPLotusNotesAddin5, WPLotusNotesAddin6, or Workshare.Client.NotesExtension.dll? If the issue happens for just one or some users, not all, the issue is likely to be related to the user-specific / profile issues. Examples: inadequate permissions, or problematic local xml files. If the issue occurs for all users on all computers in a given environment, the issue is likely to be related to the configuration of the application or to the Lotus Notes / Domino server. If mail cannot be sent through right-click > Send To > Mail Recipient, or if a Lotus Notes email interface does not result, the implication is that Lotus Notes has not been correctly set as the default email program. In order for Workshare Protect to be triggered by outgoing email messages, the Notes.ini file used by the local instance of Lotus Notes must be modified to include the calls to the Workshare / Lotus Notes add-ins. If the appropriate file name is not referenced by EXTMGR_ADDINS in the local Notes.ini file, the Workshare Protect function will not be triggered by outgoing email messages. 21