Troubleshooting Guide

A general primer on how to troubleshoot problems and report bugs, with an emphasis on Digital-Clay.

There are two alternative goals for troubleshooting problems:

1. Understanding the problem and possible causes as best as possible so that the issue might even be solved on the spot without R&D. I.e. the problem may be due to a lack of understanding or a missed detail, or it may be solved with a temporary workaround or alternative feature to replace the specific misbehaving feature.
2. Collecting as many clues and details as possible so that R&D can reproduce and fix the problem.

Since Digital-Clay is a generic tool for building solutions and no two solutions are ever the same, detailed troubleshooting and collection of information is often invaluable, if not critical, towards solving the problem. It may even be impossible to reproduce some problems in other environments simply because there are many specific and unique factors that contribute to the bug that may not exist anywhere else.

When submitting bug reports, the important question to ask is “What would R&D need to run the exact same actions that I just ran on another machine, and thereby reproduce the bug?”

Even if you can describe and reproduce the problem, R&D may not be able to recreate the environment necessary to debug the problem due to a lack of customer-specific resources or information.

The possible elements that together create a specific problem are as follows:

The code or program itself. R&D always has this so the only necessary information here is the specific product version in which the problem was found. A bug may only exist in one specific version and sometimes customers may not have the latest version or may even have a beta version installed.

This is split into the following sub-elements:

• The data. This includes records, users, permissions, tables, fields, links and field properties. In other words, the database. Roughly 20%-50% of bugs are data specific, if only because the bug only appears when using specific fields as filters or when joining two specific tables. Also, some bugs may have to do with security permissions, or form layouts, which in turn are dependent on tables and fields. For these reasons, a copy of the database is often necessary in order to reproduce the bug.

• Note that in the case of imports (Integrator), the source data is even more critical. I.e. import bugs may only be reproduced with the same source data file or database and therefore these must be included in bug reports related to problematic imports.

• The toolbar: If the problem is caused by an item launched from the main Digital-Clay Toolbar, the Toolbar.XML may be needed. Don't forget that the items in each person's toolbar are customizable and therefore unique.

• Document Templates: Any problem that has to do with generation of documents from templates must be reported along with the document template HTML file.

• The layout: If the bug appears in a data form it is usually a good idea to make a copy of the Layout.XML file and submit it with the bug report. For example, data might be misbehaving only because the specific layout has the same field twice in two different tabs.

• The configuration: Besides the data, there are various settings and customized lists. All of these are stored in either the Settings XML file or in the registry. Bugs due to specific configurations are rare and should therefore only be investigated when all else fails.

This includes every action leading to the bug. This is by far the most important element.

The critical thing to understand is that the sequence starts from the moment the Digital-Clay application is launched!

Examples:

• Which client was launched (Station, Studio).
• What username and role was used to login
• Whether the user stayed offline
• Every item the user clicks on leading to the problem.
• Every setting or field used to build a query. In other words it may be a combination of everything that was added and not just the last thing that was clicked on.

The more details the better. Sometimes it's necessary to know whether the user used the keyboard, or that he selected items in a specific order, or set/removed other options before clicking on the problematic item, etc.

Often the sequence itself isn't important but the saved details are. E.g. in an analysis query, all you have to do is add 2 specific indicators, 1 column and a filter, and the results are displayed wrong. In this case, instead of describing how to create such a query step by step, it is much simpler to save and send the saved .sgr file. Obviously, it must be verified that the .sgr file is all that's needed to reproduce the problem. Saving your actions applies in the following cases:

• Browser lists (.sls file)
• Analysis/Metric queries (.sgr file)
• Dashboards (.sds file)
• Imports (session XML file AND the source data file)

In rare cases, even seemingly unrelated actions can cause the problem. Examples:

• Have other windows open at the same time. E.g. first click on the Browser and open an item, and then open the Custom Fields and add a new field.
• Login, logout, then login again as a different user and only then does the problem occur.
• Go online, then disconnect. I.e. saying that the problem occurs offline may not be enough.

What this means is that when attempting to reproduce the bug, it is important to trace your steps as far back and in as much detail as possible. Start with the obvious last thing that was clicked on, then slowly add more and more steps until you either reproduce the bug, or you can't remember any more details.

When submitting this information in a bug report, the sequence should be described in the exact order with all steps and details that are necessary to reproduce the bug. Once you have reproduced the bug using these methods, you usually know exactly which steps are important to mention and which aren't. An example:

1. Load ClayOutlook
2. Login with administrator
3. Open a browser window but don't click on anything
4. Disconnect using the toolbar button
5. Click on a table in the browser

In rare cases, the problem may be due to the specific machine, network or server. If the problem is only reproducible on one machine, this may be the case. Examples:

• A runtime error is due to protection-software installed on that machine (Firewall, Windows DEP, Antivirus)
• Outlook misbehaviour is due to the specific PST file, some Outlook settings or the Exchange Server.
• Disconnections, strange behaviour or speed issues are due to networking problems.
• Data is not displaying correctly due to Windows Regional Settings (e.g. date formats, default language settings)
• Data is getting corrupted due to specific SQL Server settings.
• Clients don't load due to a bad installation.
• Crashes due to low memory or even bad hardware.

Obviously, these issues are always unique and need administration and troubleshooting skills. Some general techniques and tips:

• Rule out the other easier elements or obvious factors first before assuming it's the environment.
• Test the problem on another machine in a similar environment.
• Reboot.
• Uninstall and then reinstall.
• Gather as much information as possible regarding what makes this machine or environment unique. This includes OS versions, hardware, connection/network, regional settings, Outlook details, other installed software or Outlook plugins. Try to rule out as many of these factors as possible by changing the environment (for example, change relevant Outlook settings, disable a firewall, or change the way it connects to the network).
• If you think it has to do with the environment, include all the relevant environment information in a bug report.
• If R&D still can't reproduce it, the last resort left is for R&D to connect to the machine and debug the problem within the same environment. In this case the machine must be setup for remote control.

See Troubleshooting With Logs for various techniques in tracing problems to more specific causes, and for collecting information.

Try to find the problem in Known Issues.

Always try to reduce the complexity of the sequence of events. Examples:

• If by adding 5 columns and 4 filters to an analysis query, the client crashes, try removing one column and filter at a time to see if the bug is related to one specific field only.

• Does the problem also happen offline/online? Does it happen with an unrestricted user? Etc. If no/yes, then these details are important/unimportant.

• If you skip all the steps but the last, does the bug still happen? Which of the steps are critical in order to reproduce the bug? Start with the last few steps then slowly add more steps until you find the critical steps that cause the problem.

• If you change the order in which you do things, does it still happen?

• Does changing some settings or options affect the bug? Some examples: In analysis, does it work in the table but not in the graph? Does a dashboard work if you don't group together the dynamic filters? Does the automation work if you set the requirements to mandatory? Does the ClayOutlook Contact disappear if you remove the “Synchronize all Contacts” setting? Does Outlook behave better when the user is not connected to Exchange? In other words, play with any variations you can think of. This can often uncover further clues and narrow down the possibilities.

• If something used to work in the past but now has a problem, collect all the information possible as to what changed from the time it last worked until now. Examples: The version was updated, a new Outlook plugin was installed, the user's permissions were changed, a new column was added to the list.

• Always try to reproduce a bug. If you can't reproduce it, try harder. If you still can't, then just write down as many details (sequence of events) as possible and check the logs.

• Never wait until later to reproduce bugs. Never wait to reproduce a bug on another machine. As explained above, the critical elements of the bug may never be the same.

• Always save everything possible before even trying to reproduce the bug. E.g. if you get an error message while running an analysis query, save the .sgr file immediately and only then try to reproduce it. You may not remember all the details after you start changing things.

• Always write down the error message before closing an error message box. Or capture a screenshot of the error and then write it down. The exact wording of the error message is important.

• If you think the error may be in the log file, check both the client AND the Central log files. Also compare the time the problem occured with the timestamps in the log files.

• Bug report attachments: Many possible attachments were mentioned earlier and many bug reports usually need attachments. Summary:
  • Always send the saved actions whenever possible (.sgr, import session files etc.)
  • Attach the following implemention files when relevant: The Toolbar.XML if the item is in the toolbar, the Layout.XML if it's in a data form, the source file if it's an import, the HTML template if it has to with document generation.
  • R&D may need a copy or periodical update of the specific database being used. Check with R&D if in doubt.
  • If you found relevant timestamped entries in a .log file, then attach the entries as well.
  • Screenshots are only useful when the problem is visual. I.e. if something doesn't look right or the problem is too difficult to explain in words.

• Never trust anyone when it comes to details. Always check things out yourself. A critical detail may be missing or something may have been overlooked. Always reproduce and verify bugs yourself. Don't submit a bug report before you have troubleshooted and analyzed the problem as best as possible.