What is BugzScout?
BugzScout is a system which allows you to send new bugs directly to FogBugz simply by submitting an HTTP post. This is a great way to automatically report bugs into your database. This article first provides a brief overview, lists the BugzScout-related files included with FogBugz, and then provides some brief descriptions of the basic features that you may find helpful. The BugzScout system is supported on all server platforms that FogBugz is supported on.
See also Get Crash Reports from Your Users - Automatically, an article by Joel Spolsky about gathering crash reports from your customers.
BugzScout allows your program to report bugs back to your FogBugz server. For example, when your code is in beta, you may want to let users send you feature requests, and you certainly want to gather data about crashes.
Included in every FogBugz installation is a URL called scoutSubmit.asp (or scoutSubmit.php on non-Windows installations). This URL is the entry point for automatic bug submissions and is all you need in order to use the BugzScout system. When you need to submit a bug report from the field, you simply create an HTTP post containing the values that scoutSubmit.asp expects to receive, and post that directly to scoutSubmit.asp on your web server.
How Are These Bugs Handled within FogBugz?Your web server must be on a server visible from the Internet. If it is behind a firewall, you can configure that firewall to forward HTTP requests to the FogBugz server. The only file that needs to be publically accessible is scoutSubmit.asp. You may choose to configure your web server so that this is the only file accessible to the world, while keeping all the other files in the FogBugz directory protected.
Duplicate Bug Submissions - If the description field of a bug submitted via scoutSubmit.asp matches exactly to any existing bug, the following occurs:
- This new submission will be appended to the existing bug's history, and a new bug will not be created in FogBugz. So if one bug is reported by 1,000 copies of your program, only one case will be created in FogBugz for this bug. (You can over-ride that behavior if you set ForceNewBug to 1 or "true".)
- The occurrences field for the existing bug will increase by 1. (The occurrences field of a bug, e.g. "3 occurrences", appears only when there is more than one occurence of that bug.)
- FogBugz will return a status message to the person who submitted the bug. If there is already a case in FogBugz with the same description as this new bug, and that case has a "Scout Message" specified, that message will be returned to the customer. Otherwise, the ScoutDefaultMessage text will be returned to the customer. An example of a default message could be something general like "Thank you, your bug report has been received", or it could contain instructions for a workaround for this bug.
When you edit a bug submitted via scoutSubmit.asp, the case will have two new fields:
- Scout Msg
Type in a custom message to be returned to the next person who submits this same bug, i.e. if and when a bug with the same description is submitted again. You could use this to provide the user with instructions for a workaround for this bug, or tell the user that this bug has been fixed for the next release. - Scout Will
This controls whether or not future duplicates of this case will be appended to this case. If it is set to "Stop Reports", future submissions with the same description will not be added to FogBugz in any way. "Continue Reporting" simply means that future duplicates will continue to be appended to this case.
Sample Files
In the Accessories directory of FogBugz for Windows there is a file named ScoutSample.zip that contains examples of how to use BugzScout. There is a BugzScout mini-app that submits HTTP posts to scoutSubmit.asp for you (available in both C# and C++ incarnations), and there is ScoutSample (available in both C# and VB) which provides examples of how to use BugzScout. Source files are included for everything, with helpful comments (particularly in the C# files). Click here to see the interface to ScoutSample (VB version shown), with usage tips for the fields involved.
For readability, please make sure your Description field uses a carriage return / line feed line separator. For example, you could do this before submitting the report to BugzScout if you need to get the CRLF in there: Replace(strCrashReport, "\n", "\r\n").
Following is a brief description of the key files and folders in ScoutSample.zip:
.Net/C# version:
- BugzScout.Net\BugzScout
A .Net object version of BugzScout, including C# VS.Net Project source files.- BugzScout.Net\BugzScout\bin\Release\BugzScoutDotNet.dll
The compiled C# BugzScout .Net object.- BugzScout.Net\ScoutSample
A C# project that uses the BugzScout .Net object. Use this as an example of how to submit cases to FogBugz from your own code, reporting the stack trace and other helpful information.- BugzScout.Net\ScoutSample\bin\Release\ScoutSample.exe
Double click on this to see BugzScout in action. This is a simple Windows program that collects information from the user and passes it to BugzScout, which in turn submits the new case to FogBugz.C++ and VB version:
- BugzScoutCPP
A C++ ActiveX object version of BugzScout including source files.- BugzScoutCPP\howto.html
Instructions specific to the C++ ActiveX version, and example VB code with documentation.- BugzScoutCPP\ScoutSample
A VB project that uses the C++ ActiveX object. Use this as an example of how to submit cases to FogBugz from your own code.- BugzScoutCPP\ScoutSample\ScoutSample.exe
Double click on this to see BugzScout in action. This is a simple Windows program that collects information from the user and passes it to BugzScout, which in turn submits the new case to FogBugz.HTML example:
- BugzScoutCPP\ScoutSample\scoutsample.html
A sample HTML form which publishes the relevant info to FogBugz. This file explains the different variable arguments to the scoutSubmit.asp file in your FogBugz install. You could customize it to allow users to submit bugs directly through an HTML form.
