BugzScout is a simple API which allows you to send new bugs directly to FogBugz simply by submitting an HTTP POST request (GET is also supported but not recommended). This is a great way to automatically report bugs into your FogBugz tracker from any of your websites or applications, as long as they have access to the Internet.

BugzScout allows your program to report bugs back to your FogBugz server. For example, for each version of your application that you release, you can gather and consolidate data about crashes or even let users send you feature requests straight into FogBugz.

The URL of this API is http://your.fogbugz.url/scoutSubmit.asp. 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.asp on your FogBugz account.

How Does it Work?

The scoutSubmit.asp endpoint expects an HTTP Post request with the following values:

  • ScoutUserName
    • The full name of the FogBugz user the case creation or edit should be made as. We recommend using a Virtual User for this.
  • ScoutProject
    • The Project that new cases should be created in (must be a valid project name). Note that if BugzScout appends to an existing case, this field is ignored.
  • ScoutArea
    • The Area that new cases should go into (must be a valid area in the ScoutProject). Note that if BugzScout appends to an existing case, this field is ignored.
  • Description
    • This is the unique string that identifies the particular crash that has just occurred. BugzScout submissions will be consolidated into one case based on the Description. When a BugzScout submission arrives in FogBugz, if there are no existing cases with the exact same Description, then a new case is created in the ScoutProject and ScoutArea. If a case is found with a matching description, the new submission is APPENDED to that case’s history, and a new case will NOT be created in FogBugz. When appending to a case, the ScoutProject and ScoutArea fields are ignored.
    • Because BugzScout submissions are automatically consolidated, it is important to include appropriate information when constructing the Description. We always include the short error message that was generated, and then some additional information. For example, it is usually wise to include the application version number so that a similar crash in version 1.1 and in version 1.2 will NOT append to the same case. You may consider including the OS that the crash occurred on, if relevant.
    • Here is a good starting point:
      MyAppName X.Y.Z SomekindofException: Exception message text here which yields something like this actual error from part of the FogBugz javascript code: FogBugz-8.9.72.0H: JS Error: TypeError: 'undefined' is not an object (evaluating 'bug.ixBug')
  • Extra
    • The details about this particular crash. This is often a good place to put a stack trace, operating environment information, HTTP headers, or other details about what might have caused the error. Include as much information as you can, but beware of sending sensitive information. For example, in billing code, make sure your exception handling code strips out credit card information.
  • Email
    • An email address to associate with the report, often the customer’s email. This overwrites the correspondent field on the case with each appended occurrence, so it is automatically included at the end of the case event as well.
  • ForceNewBug
    • An option to override the normal automatic consolidation of BugzScout reports. If this is set to “1″ or “true”, then a new case will always created from this submission.
  • ScoutDefaultMessage
    • This is the default text that will be returned by the HTTP post request. If the submission is appended to an existing case, and that case has some text in the “Scout Message” field, then that text will be returned instead. This is useful when you want to let your first user experiencing a crash know that “we are investigating the issue,” but update that message in the case later on when you know that “this problem is fixed in the next version.”
  • FriendlyResponse
    • Set to “1″ or “true” in order to get a response in HTML format. By default, the response will be XML.

 

How are these bugs handled within FogBugz?

BugzScout cases in FogBugz have a slightly different appearance than regular cases, and include a couple of new fields:

  • Occurrences
    • This field indicates the number of times a BugzScout submission has been consolidated into this case. It will only appear when the value is greater than 1. This is always updated on new submissions, regardless of the value of the “Scout Will” field.
  • Scout Message
    • A custom message to be returned when the next BugzScout submission matches this case, i.e. if and when a case with the same Description is submitted again. You could use this to provide the user with instructions for a workaround for the error, or tell the user that this bug has been fixed for the next release.
  • Scout Will
    • This controls whether or not future submissions that match this case’s Description will be appended to it or not. If it is set to “Stop Reports”, future submissions with the same description will not be added to this case. Since the case will not be edited, the user it is assigned to will not receive a notification. “Continue Reporting” simply means that future submissions with the same Description will continue to be appended to this case.
    • Newer versions of FogBugz will automatically change this field to “Stop Reports” after 50 occurrences. The field will show how many remaining occurrences will be logged. See this blog post for more information on this change in BugzScout.
    • Note that if you change this field to “Stop Reports” or FogBugz does so automatically, the occurrence count and last occurrence date and time will still update when new submissions are received.
  • Last Occurrence
    • This field shows the most recent date and time of submission. This is always updated on new submissions, regardless of the value of the “Scout Will” field.

 

Examples for Integrating with scoutSubmit

We have created a sample file which contains examples for two basic methods of sending this HTTP post.

  • scoutsample.html (in the sample zip file at “BugzScoutCPP\ScoutSample\”)
    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 (for FogBugz for your Server only)
    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 frmMain.vb 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 (including file attachments), while still getting the benefits of BugzScout (automatically appending to existing cases, occurrence count, etc). The trade-off is that it requires a logon token.