BugzScout is included with every licensed (for-your-server) FogBugz installation as well as FogBugz On Demand. The URL of this API is http://your.fogbugz.url/scoutSubmit.asp (for pre-FogBugz 7 on Linux/Mac, it's scoutSubmit.php). This URL is an entry point for automatic bug submissions. The way it works is that you create an HTTP post containing the values that it expects to receive, and post that directly to scoutSubmit on your web server. (If your web server is behind a firewall, remember to allow the scoutSubmit file to be seen by the public, but not the other ASP/PHP files on your FogBugz installation.)
How do I submit bugs to scoutSubmit?
For Licensed FogBugz, included in your FogBugz/accessories folder there is a zipped folder called ScoutSample.zip which contains examples for the two methods of sending this HTTP post. If you are using FogBugz On Demand, you can download the sample code here.
- scoutsample.html
An HTML form that posts to scoutSubmit. Just open this in your browser and follow the directions on the form, it's easy to use.
- ScoutSample.vbp
Included with Licensed FogBugz, this is a simple VB project that shows you how to interact programatically with our free BugzScout ActiveX control (BugzScout.dll in the Accessories folder), which packages up the values for you and posts them via HTTP to scoutSubmit.asp. If you do not have the tools to open a VB project, you can click here to view some of the source code for the form - we stripped out the UI stuff and left in the parts that interact with the BugzScout control.
ScoutSample.exe is the compiled result of this VB project, just double click on it to run it. Click here to see the interface, with usage tips for the fields involved.
- The XML API
You can also submit cases using the XML API and specify that they are BugzScout cases. This allows you to take advantage of the many features of the API, while still getting the benefits of BugzScout (automatically appending to existing cases, occurance count, etc). The trade-off is that it requires a logon token.
How are these bugs handled within FogBugz?
Duplicate bug submissions: If the description field of a bug submitted via scoutSubmit matches exactly to any existing bug, this new submission will be APPENDED to the existing bug's history, and a new bug will NOT be created in FogBugz. (You can over-ride that behavior if you set ForceNewBug to 1 or "true".) The following two things will also happen:
- 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 are more than one occurences of that bug. In FogBugz 3.x it is present only in the List view, not the Grid view.)
- 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."
When you Edit a bug submitted via scoutSubmit, you have these 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.
For more information on automatically collecting bugs from the field, see the 7.0 help doc for BugzScout (applies to FogBugz 8 as well).
