Introducing Triage

tri-age, n. 1. the process of sorting through differences in software and hardware configurations to diagnose and solve problems reported by users. 2. the determination of priorities for action in response to a support call.

Triage consists of three separate components:

  • Triage Wizard for building application profiles.
  • Triage Client for generating audit reports.
  • Triage Analyzer for diagnosing problems.

What is Triage? explains how these three components work together to help you diagnose and solve customer support problems.

Using Triage with your Application gives you an overview of how you set up Triage to support a specific application.

Distributing Triage Client describes the Triage files you have to ship with your application.

Packaging Triage Client for the Web describes how to package Triage Client so users can download it from your Web site.


What is Triage?

Collecting information is a big part of customer support. Much of the time spent solving installation and configuration problems is spent collecting the information necessary to identify the problem.

Triage provides a set of tools to automate this process. First, there is Triage Client, which you distribute to your users. Triage Client audits a user's machine configuration and generates an audit report.

But what information should this audit report contain? Every application installs a different set of files, depends on different DLLs, and adds its own registry entries. To handle this, you use Triage Wizard to define an application profile. An application profile determines what information appears in the audit report.

This leaves one final question: given an audit report for a user's machine, how do you identify possible problems with the machine setup? The answer is Triage Analyzer. Triage Analyzer compares an audit report for a user's machine with an audit report for a working installation of the application, and identifies the differences.

 | Used By | To
Triage Wizard | Support personnel | Build an application profile.
Triage Client | Support personnel | Generate a reference audit report for a working installation.
 | End user | Generate an audit report.
Triage Analyzer | Support personnel | Compare a user's audit report with the reference report.


Using Triage

Using Triage with your Application

The following steps describe the general procedure for using Triage:

Step 1: Use Triage Wizard to build an application

Step 2: Generate an audit report for a working installation of your application.

Step 3: Distribute Triage Client and the application profile to your customers.

Step 4: Diagnose problems.

Step 1: Use Triage Wizard to build an application profile.

Triage Wizard steps you through the process of building an application profile.

When you're finished, you have a profile that specifies what you want to know about a user's machine: its operating system, hardware configuration, environment variable settings, registry entries, and the system and application files installed on the machine.

Topic link | Building Application Profiles

Step 2: Generate an audit report for a working installation of your application.

Run Triage Client on a machine where your application installs and runs properly.

Open the application profile and generate an audit report. This audit report is your reference report. When users send you their audit reports, you'll use Triage Analyzer to compare these audit reports with the reference report.

The idea is that by comparing a working configuration with a problem configuration, you can identify what's wrong with the user's machine.

Topic link | Generating Audit Reports

Step 3: Distribute Triage Client and the application profile to your customers.

When a user has a problem with your application, you can ask them to run Triage Client. Triage Client is an easy-to-use utility that, with a few mouse clicks, generates an audit report describing the software and hardware configuration of the user's machine.

The user then sends the audit report to you via e-mail, all from within Triage Client. The user can even choose to compress the audit report before sending it. Compressed reports are stored in .CAB (cabinet) files, which can be loaded directly into Triage Analyzer.

You can distribute Triage Client with your application, or package it for download from the Web.

Topic link | Distributing Triage Client
Topic link | Packaging Triage Client for the Web
Topic link | Generating Audit Reports

Step 4: Diagnose problems.

Triage Analyzer compares an audit report submitted by a user with a reference report and highlights the differences. This lets you quickly identify possible problems.

You can print out diagnostic reports that show the differences between a user's machine and the configuration of your reference machine.

You can also print out the reference and audit reports in a convenient tree format.


Building Application Profiles with Triage Wizard

An application profile specifies what information you want Triage Client to include in the generated report when it audits a user's machine.

For example, you may want to know what version of a DLL is installed on a user's machine. Or, if there are multiple versions of the same DLL installed, which one comes first in the PATH environment variable.

Topic link | What is a Profile?
Topic link | Building Reusable Templates
Topic link | Auditing File Information
Topic link | Checking ActiveX Controls
Topic link | Checking Shortcuts
Topic link | Using Macros
Topic link | Running Triage Wizard from the Command Line


What is a Profile?

An application profile specifies what information you want to see in an audit report for a user's machine. An application profile can include the following audit items:

  • Operating System info such as display settings, International settings, and Windows version.
  • System resource information that describes the current state of the user's machine. This includes information such as the amount of free disk space, what DLLs are loaded into memory, what applications are running, and how much system memory is available.
  • Hardware information such as the amount of RAM and the type of graphics card.
  • File information such as date, time, version, and location.
  • ActiveX controls.
  • Shortcuts.
  • Contents of ASCII files such as .INI, .SYS, and .BAT files.
  • Environment variable settings.
  • Registry entries.

To build an application profile, you use Triage Wizard.

Application profiles are saved in .TRP files. A .TRP file is an ASCII file.


Defining Reusable Templates

Applications often depend on components, such as OLE 32 or ODBC, that are shared by many applications. Triage Wizard allows you to define profiles for shared components, and then include these component profiles (otherwise known as templates) in any application profile.

Using templates makes it easier to build and maintain profiles, because common profile information is not repeated in every profile. When you need to edit the profile of a shared component, you don't have to edit every application profile. You just have to edit the template for that shared component.

Shared components can be system components such as OLE and ODBC, or application-specific components shared by a family of similar applications. For example, if you ship several different versions of the same application, you can use a template to hold the profile information common to all versions of the application. Each application profile then includes the template, and adds profile information specific to that version.

Templates are saved in .TRT files. Like a profile file (.TRP), a .TRT file is an ASCII file.


Auditing File Information

A profile (or template) includes a list of application files that you want to audit. To include files in a profile, you can:

  • Select files from the folders on your computer or on any other computer in the network neighborhood.
  • Import an InstallShield packing list.
  • Add all DLLs that one of your application DLLs depends on.

Tips

  • To see what information Triage Client will collect for a file during an audit, click Properties.

  • By default Triage Client searches for files on the local hard drives of a user's machine. If you want Triage Client to also search network or CD-ROM drives by default, select the Include Network Drives and Include CD-ROMS check boxes.

    Users can change these defaults when they run Triage Client.


Checking Shortcuts

A profile (or template) can include a list of shortcuts (.lnk files) to check. For example, you can set up a profile to check that a shortcut exists and that it points to the correct target.

For each shortcut listed in the profile, an audit report includes shortcut properties such as the shortcut's target, arguments, and working directory.

To add shortcuts to a profile

  • In the Shortcut Files dialog box, click Add and then select shortcut files from any of the folders on your desktop. You can also type the name of a shorcut file in the File Name box.


Checking ActiveX Controls

A profile (or template) can include a list of ActiveX controls (.ocx or .dll files) to check. For example, you can set up a profile to check that a DLL is registered correctly.

For each ActiveX control listed in the profile, an audit report includes the CLSID, InProcServer32, and ProgId values found in the registry, as well as the name and location of the file.

To add ActiveX controls to a profile

  • In the ActiveX Controls dialog box, click Add and then select .dll or .ocx files from any of the folders on your desktop. You can also type the name of a file in the File Name box.


Using Macros

You use macros to specify the paths to files, ActiveX controls, and shortcuts. A macro represents a file path that can vary from machine to machine. For example, the location of the Windows folder can vary from machine to machine, and different users can install an application in different directories.

If your application stores paths in the registry, you can use macros to look for files, ActiveX controls, and shortcuts only in those locations. Otherwise, Triage Client searches the entire machine.

Similarily, if you know that a file should be in the Windows folder, you can use a macro to search only the Windows folder.

Triage Wizard provides two types of macros:

  • user-defined macros for searching folders whose paths are stored in the registry.
  • predefined macros for searching system folders such as the Windows folder.


Defining and Using Macros

A user-defined macro represents a named value stored under a registry key. You use these macros to specify file paths when you add files to copy, ActiveX controls, or shortcuts to a profile.

For example, suppose an application stores its installation directory in the registry:

If you want Triage Client to look for files, ActiveX controls, or shortcuts in this installation directory, you can define a macro for the InstallDir registry entry:

Then you can use this macro to specify the location of the file. Just select a file and type the string "$(CensusInstallDir)\" in front of the file name:

The CensusInstallDir macro represents the InstallDir entry under the HKEY_LOCAL_MACHINE\SOFTWARE\Metaquest\Census97\General registry key.

When Triage Client audits a user's computer, it replaces $(CensusInstallDir) with the value of the InstallDir entry in the user's registry.

When you use a macro to specify the path to a file, Triage Client looks only in that location for the file. Otherwise, Triage Client searches all drives for the file.

What do you want to do?
Topic link | Define a macro
Topic link | Use a macro to specify a file location


Using the Pre-defined Macros

Triage Wizard provides two predefined macros:

  • WinDir represents the Windows folder (for example, "c:\windows").
  • WinSysDir represents the System subfolder (for example, "c:\windows\system").
What do you want to do?
Topic link | Use a macro to specify a file location


Running Triage Wizard from the Command Line

You can automatically load profiles and templates by running Triage Wizard from the command line. For example, you could create a shortcut with the following target:

"C:\Program Files\MetaQuest\Triage\TriageWizard.exe" /profile="myapp.trp"

This shortcut starts Triage Wizard and loads the profile myapp.trp. The /profile switch also supports templates (.TRT files).


Distributing Triage Client

Typically, you distribute Triage Client on the same CD (or disks) with your application files. You could also allow users to download Triage Client from your web site.

Important If you want to be able to diagnose installation problems, do not compress Triage Client files.

To distribute Triage Client, you need to include the following files:

  • The Triage Client executable (TriageClient.exe).
  • The application profile for your application (.TRP file).
  • Any templates (.TRT files) referenced by the application profile.
  • The client.htm file. Triage Client loads this file when the user clicks the Help button. If the file is not present on the local system, Triage Client loads www.metaq.com/client.htm. You can replace the version of client.htm supplied with Triage with your own verson.

Tip When you save a profile, Triage Wizard can build the set of Triage files (including a copy of Triage Client) that must be shipped with your application.

Just click the Save and Generate option to copy the profile and any included templates to a specified directory. If you want to copy Triage Client to the same directory, select the Copy Triage Client check box.


Packaging Triage Client for the Web

Instead of shipping Triage Client with your application, you can set up a web page from which users can download and automatically run Triage Client.

Triage Wizard can generate a download package for Triage Client. A download package is a collection of files that can be copied from a Web server to a user's machine.

A Triage Client download package consists of a single compressed file (a .CAB file, also know as a "cabinet") that contains all the files that need to be downloaded to audit a user's machine.

The cabinet file includes a special configuration file named CAB.INF. Through this configuration file, you specify the command-line arguments for Triage Client.

When a user downloads the CAB file, the system extracts the CAB contents into a temporary directory and runs Triage Client. After Triage Client finishes the audit, it sends the generated audit report back to you.

Triage Wizard also generates the HTML code for a web page that automatically downloads the Triage Client package.

To package Triage Client for the Web

  1. Edit the list of files in CAB.TXT. This file lists the files that will be put in the CAB file along with the profile, any templates, and the .INF file. You can find this file in the Triage installation directory.

  2. Edit the configuration file template (CAB.INF). This file specifies the Triage Client command-line arguments.

  3. Edit the Web page template.

  4. Generate the package and the Web page.

  5. Add the Web page to your Web site.


Editing the Configuration File Template

The CAB.INF file is a template for the configuration file that Triage Wizard puts in the CAB file. You can find CAB.INF in the Triage installation directory.

In CAB.INF, the [TriageClientInstaller] section specifies the Triage Client command line:

[TriageClientInstaller]
run=%EXTRACT_DIR%\TriageClient.exe /profile="Triage.trp"
; note that the arg key is appended to the run key in the
; generated INF file. The /profile and /mail command line arguments
; are automatically appended to the arguments.
args=/smtp="smtp.hip.cam.org"

When Triage Wizard generates a .INF file, it:

  • Updates the /profile switch with the profile name you entered in Triage Wizard.
  • Adds the /mail switch using the address you entered in Triage Wizard.
  • Adds the arg key to the run key

To add switches to the default Triage Client command line, edit the definition of the args key. For example, if you are using Internet mail you have to insert the name of your SMTP server. Triage Wizard does not take the SMTP server name you enter in the Product Information dialog.

If you dont use Internet mail, then remove the /smtp switch from the arg key.


Editing the Web Page Template

The CAB.HTM file is a template for the Web page that Triage Wizard puts in the CAB file. You can find CAB.HTM in the Triage installation directory.

The generated file is named profile_name.HTM. You can modify any part of the generated .HTM file except for the <OBJECT> tag:

    <object id="TriageXCab"
    classid="CLSID:06889605-B8D0-101A-91F1-00608CEAD5B3"
    codebase="YourFile.cab#Version=1,1,0,0" align="baseline"
    border="0" width="0" height="0"><param name="_Version"
    value="65536"><param name="_ExtentX" value="2646"><param
    name="_ExtentY" value="1323"><param name="_StockProps"
    value="0"><param name="NeedlePosition" value="2"></object>:

The <OBJECT> tag downloads the CAB file into a temporary directory, extracts all the files from the CAB file, and then runs the instructions specified in the CAB.INF file.

Note that this HTML code assumes that the CAB file is located in the same directory as the HTML file.


Generating the Triage Client Package

To generate the Triage Client package, you use Triage Wizard:

  1. Open an existing profile or create a new profile.

  2. In the Product Information dialog box, enter your support e-mail address.

  3. In the Save dialog box, select both the Include the Triage Client executable and Package Triage Client for Web check boxes. Then click the Save your profile and Copy all the files button.

  4. Enter a name for the profile.

  5. Select the folder where you want Triage Wizard to put the package.


Generating Audit Reports with the Triage Client

Generating Audit Reports with Triage Client

Triage Client is an lightweight, easy-to-use program that you either ship with your application or make available from your Web site. Users run Triage Client to generate audit reports that detail the software and hardware configurations of their machine.


What is an Audit Report?

An audit report is a detailed list of information about the hardware and software configuration of a user's machine. An audit report includes information about files, environment variables, registry entries, hardware, and operating system.

There are two types of audit reports:

  • Audit reports generated by users when they have installation and configuration problems.

  • Reference reports generated by you. Reference reports are audit reports you generate on machines where there are no installation or configuration problems. You use Triage Analyzer to compare reference reports with the audit reports submitted by users.


Generating Audit Reports

To generate audit reports, you use Triage Client. Triage Client allows users (and you) to load profiles and generate audit reports.

By default, Triage Client lists the profiles found in the current directory.

What do you want to do?
Topic link | Add a profile to the list
Topic link | Generate an audit report


Running Triage Client from the Command Line

You can automatically load a profile and generate an audit report by running Triage Client from the command line. For example, the following command starts Triage Client and generates an audit report for myapp:

TriageClient.exe /profile="myapp.trp"

If you put this command in a script file or a shortcut, users don't have to worry about loading the correct profile. All they have to do is edit, save, and send the generated audit report.

You can also automatically save the audit report or send it via e-mail. For example, you could create a shortcut with the following target:

"C:\Program Files\MetaQuest\Triage\TriageClient.exe"
    /profile="myapp.trp" /save="myapp" /mail="me@address.com"

When a user double clicks this shortcut, it automatically loads the profile, generates the audit report, saves it to disk, and sends it back to you.

By default, Triage Client uses MAPI mail to sent the audit report. If you want to send audit reports with Internet mail, use the /smtp switch to specify the SMTP server:

"C:\Program Files\MetaQuest\Triage\TriageClient.exe"
    /profile="myapp.trp" /save="myapp" /mail="me@address.com"
    /smtp="smtp.hip.cam.org"

Note: When the command line includes the /save or /mail switches, Triage Client generates the audit report, saves or mails it, and then exits.


Diagnosing Problems with the Triage Analyzer

Diagnosing Problems with Triage Analyzer

To diagnose installation and configuration problems, you use Triage Analyzer. Triage Analyzer compares an audit report generated on a user's machine with a reference audit report. A reference report is an audit report generated on a machine where your application runs without any problems.

Triage Analyzer provides a visual comparison of two audit reports. It displays the audit reports side by side, and highlights the differences. This helps you to identify the differences in machine configurations that may be the cause of the user's problems.


Comparing Audit Reports with Reference Reports

Comparing an audit report with a reference report is easy with Triage Analyzer. First, load the two reports. Select a reference report you generated for your application. Then select an audit report submitted by a user who reported a problem with your application.

Triage Analyzer displays the two reports side-by-side and highlights the differences between the two reports.

To help diagnose the problem, you can show only the differences. Or you can filter out differences (such as file locations) that are unlikely to have caused the reported problem.

If the audit reports contain file information for more than one operating system (for example, if a user has both Microsoft® Windows 95 and Windows NT® installed), you can show only the files for the active operating system.

What do you want to do?
Topic link | Diagnose an installation or configuration problem
Topic link | Show only the differences between two audit reports
Topic link | Filter out items from the audit reports
Topic link | Show only file information for the current operating system
Topic link | Change the colors used to highlight differences
Topic link | Print or save a diagnostic report


Printing and Saving Diagnostic Reports

Printing and Saving Diagnostics

Triage Analyzer can print or save a diagnostic report that summarizes the differences between the reference report and an audit report. Diagnostic reports are saved in .TRD files.

Sample diagnosic report:

Diagnostic report for Census 97
> Reference report - C:\Program Files\MetaQuest\Triage\Census97Reference.tra
< Audit report - C:\Program Files\MetaQuest\Triage\Customer.tra

 > Hardware.RAM.0=24 Mbytes
 < Hardware.RAM.0=48 Mbytes
 > Environment Variables.Path=C:\WINDOWS;C:\WINDOWS\COMMAND;
 < Environment Variables.Path=C:\WINDOWS;C:\WINDOWS\COMMAND;C:\BIN;

> Registry=HKEY_LOCAL_MACHINE\SOFTWARE\Metaquest\Census97\.1=CensusVersion\Minor="01"
 < Registry=HKEY_LOCAL_MACHINE\SOFTWARE\Metaquest\Census97\.1=CensusVersion\Minor="00"


Editing Reference and Audit Reports

You can delete audit items from either the reference report or the audit report. For example, as you eliminate possible problems, you can delete the corresponding audit items from the reports. Or you can delete all audit items that are the same in both reports.

To delete the highlighted audit item, click Delete in the Edit menu.

You can then save the stripped down reports under different file names (in the File menu, click Save Reference As or Save Audit As).


Running Triage Analyzer from the Command Line

You can automatically load audit reports and run diagnostics from the command line. Triage Analyzer supports the following command-line arguments:

  • /ref="reference report".tra
  • /audit="audit report".tra
  • /saveto="diagnostic output".trd

For example, the following command starts Triage Analyzer and loads a reference report:

TriageAnalyzer.exe /ref="reference.tra"

If your application runs on several different configurations (for example, Microsoft Windows 3.x, Windows 95, and Windows NT), you can create shortcuts that load the required reference report for each configuration.

You could also write a script to automatically save a diagnostic report whenever you receive an audit report from a customer. The following command compares two audit reports and saves a diagnostic report without ever bringing up the Triage Analyzer user interface:

TriageAnalyzer.exe /ref="reference.tra" /audit="audit.tra" /saveto="diff.trd"


To add required DLLs

  1. In the File Information dialog box, select one of your application DLLs and click Properties.

  2. Click the DLL Dependencies tab to browse the hierarchy of DLLs that your application DLL depends on.

  3. Click Add All to add all the required DLLs to the list at the bottom of the dialog box, or click Add Selected Item to add just the selected DLL.

  4. Click Ok to add the DLLs to the profile.


To add a profile

To add a profile to the list

  1. Click Browse.

  2. Select a profile (.TRP file) and click Add.

Notes

  • By default, Triage Client lists the profiles found in the current directory.

    When you use Browse to load a profile from another directory, Triage Client adds the profile to the registry. The next time you run Triage Client, it will list all profiles in the current directory and all profiles in the registry.

  • After you add a profile, you can open it and generate an audit report.


To generate an audit report

  1. Select a product profile and click Open.

  2. Click Options, click the Drives tab, and select the drives you want Triage Client to audit.

  3. Start the audit.

Notes

  • After you generate an audit report, you can view and edit the report.

    For example, you may want to review the audit report and delete any information you don't want to send to your software vendor. Note that after you exit Triage Client or load another profile, you cannot reload saved audit reports.

  • To print audit reports, use Triage Analyzer.

  • Before you save or send an audit report, click Options and enter information about yourself, the product, and product version. This information is included in the audit report.

  • While Triage Client audits your computer, it displays a series of progress messages in its status bar.

  • To cancel an audit, click the Red Traffic Light button or exit Triage Client by clicking the Exit button.


To change the colors used to highlight differences

  1. In the Edit menu, click Options.

  2. Select a color for unmatched items.

    These are audit report items that do not match in the two audit reports, either because the item is different in each report or missing in one of the reports.

  3. Select a color for the audit report categories (for example, Operating System, System Resources, or Registry) that contain unmatched items.


To define a macro

  1. In the Copy Files, ActiveX Controls, or Shortcut Files dialog box, click Macros.

  2. In the Macro dialog box, click Add.

  3. In the Name box, enter a name for the macro.

  4. Click the ... button beside the Registry Key box, and then select a registry key in the Registry Viewer.

  5. In the Registry Value box, enter the name of a value stored under the registry key.

  6. Click Apply to fill in the Registry Data box.

  7. Click Ok to save the macro.


To diagnose an installation or configuration problem

  1. Start Triage Analyzer.

  2. In the File menu, click Open Reports.

  3. Select the reference report for a working configuration.

  4. Select an audit report submitted by a customer.

  5. Click Ok to load and compare the two reports.

Notes

  • Customers can submit compressed audit reports, which are stored in .CAB files. Triage Analyer automatically extracts audit reports from .CAB files and loads them.

  • Triage Analyzer automatically highlights differences between the two reports.

  • To view only the differences between the two audit reports, click Show Differences in the View menu.


To filter out items from the audit reports

  1. In the Edit menu, click Options.

  2. In the Filters tab, clear the check boxes for the audit items you want to filter out.

  3. Select when to apply the filter:

    • Select Always to apply the filter to both the Show Differences and Show All views.

    • Select When viewing "Differences Only" to apply the filter to the Show Differences view but not the Show All view.

      This allows you to filter out items, such as file locations, from the list of differences but still see all audit items by switching back to the Show All view.

    • Select Never to disable filtering.

Notes

  • Triage Analyzer saves the filter settings, so each time you compare two audit reports the same items are filtered out.

  • Filtered items are never highlighted when they are different (even if you don't apply the filter).


To show only file information for the current operating system

  1. In the Edit menu, click Options.

  2. Click the General tab.

  3. Select Ignore files in the non-active operating system.


To import files from an InstallShield Packing List

  • In the File Information dialog box, click Import and select the packing list file. Triage Wizard automatically extracts the names of the application files, DLLs, and system files from the packing list.


To select files to include

  • In the File Information dialog box, click Add and then select files from any of the folders on your desktop. You can also type the name of the file in the File Name box.

Notes

  • To select multiple files, hold down the CTRL key and then click each file you want to select. Hold down the SHIFT key to select a range of files.

  • You can include files in a profile even if they do not exist on your desktop. Just enter the file names in the File Name box.


To print audit reports

  1. Start Triage Analyzer.

  2. Open a reference report or an audit report. If you just want to print the report, you don't have to open both reports.

  3. Click Ok to load the report.

  4. In the File menu, click Print Reference or Print Audit, depending on which report you want to print.

  5. Set the header and footer text, fonts, and margins.

  6. Click Print.

To print part of an audit report

  1. Click the + symbol to expand the sections of the report you want to print.

  2. In the File menu, click Print Reference or Print Audit, depending on which report you want to print.

  3. Under Print Selection, click the Print Visible Items.

  4. Click Print.


To show only the differences between two audit reports

  • In the View menu, click Show Differences.


To use a macro

  1. In the Copy Files, ActiveX Controls, or Shortcut Files dialog box, click Add.
  2. In the File Name box, enter a file name in the following format:
    $(macro)\file.ext


Overview

What is Triage?

Using Triage with your Application