BugzScout is a simple API 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 from any website or application with access to the Internet.
BugzScout allows your program to report bugs back to your FogBugz server. For example, when your code is in beta, you can gather data about crashes and let users send you feature requests.
FogBugz has a URL called scoutSubmit.asp (or scoutSubmit.php on non-Windows installations). This URL is the entry point for automatic bug submissions. 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 the FogBugz server.
The web server must be on a server visible from the Internet. If it is behind a firewall, you should 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.
The following HTML code demonstrates a minimal HTML file that submits a bug to FogBugz.
<form method="post" action="http://www.example.com/fogbugz/ScoutSubmit.asp">
Username:
<input type="text" value="FogBUGZ User Name" name="ScoutUserName">
Project:
<input type="text" value="Existing Project Name" name="ScoutProject">
Area:
<input type="text" value="Existing Area Name" name="ScoutArea">
Description:
(If the description field matches exactly to any other bug, this submission
will be APPENDED to that bug's history, and a new bug will NOT be created.
The occurrences field for this bug will increase by 1.)
<input type="text" value="Description" name="Description">
Always Create New: (1 to force FogBUGZ to create a new bug for this entry, 0
to append to bug with matching description)
<input type="text" value="0" name="ForceNewBug">
Extra Info:
<input type="text" value="extra info" name="Extra">
Customer Email:
<input type="text" value="customer@emailaddress.com" name="Email">
Default Message:
<input type="text" value="html Default Message" name="ScoutDefaultMessage">
Friendly response:
(1 to respond in HTML, 0 for XML)
<input type="text" value="1" name="FriendlyResponse">
<input type="submit">
</form>
Here's what a BugzScout case looks like in FogBugz:
The actual text of the case comes from the "Extra" field.
Occurrences
Tracks how many times a case with the same description has been submitted, so you can find the most common crashes and fix those first.
Scout Message
Allows you to specify a custom message to be returned to the next person who submits this same bug. 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
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.
BugzScout includes a mechanism to insure that if a large number of users report the same crash, the reports are collapsed into a single case rather than opening multiple cases. That is done through the Description field. If the Description field matches that of a previously-submitted case:
In the Accessories directory of FogBugz for Windows there is a file named ScoutSample.zip that contains examples of how to use BugzScout (also available from our website). 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).
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.