BugzScout

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 (also accessible at scoutSubmit.php on non-Windows servers). 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="https://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 Notes

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:

  1. This new submission will be appended to the existing case history, and a new case will not be opened. (You can override that behavior by setting ForceNewBug to 1.)
  2. The occurrences field for the existing bug will increase by 1.
  3. 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.  
  4. FogBugz determines which case a new report should be appended to based on a match between the submitted Description and a hidden field in the FogBugz case, sOriginalTitle. This means that you can feel free to change the title of a BugzScout case without preventing future reports from appending to it.

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 (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:

C++ and VB version:

HTML example:

Release notes for the latest versions of FogBugz

Documentation for the latest versions of FogBugz

FogBugz 7 Documentation Home