Overview

The scoutSubmit API endpoint of the BugzScout feature allows you to send bugs directly and easily to FogBugz by submitting an HTTP POST request (GET is also supported but not recommended) from any of your websites or applications without requiring an API token.

BugzScout (compared to the more complex FogBugz API) provides a simpler interface aimed specifically at bug reporting, including an automation for aggregating similar reports into one case (bug).

Information

What Can It Be Used For

Few examples of what this endpoint can be used for:

• gather and consolidate data about crashes
• let users submit cases straight into FogBugz without having to log in
• log or submit any useful information composed of two parts: Title, Details. Entries having the same Title will be aggregated in the same case.

Back to the top

Entry Point

BogScout API URL endpoint: http://your.fogbugz.url/scoutSubmit.asp

How does it work

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

(*) marks mandatory parameters

• ScoutUserName (*)
  • The full name (not the email) 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). If append is made 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). If append is made 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 first 255 characters of the Description (not based on the case (bug) title).
  • Case Creation vs Appending to case history
    • when submitting the first time, a check is made based on the first 255 characters for an existing submission. If none found, the case is created in the ScoutProject and ScoutArea, adding as the first comment the Description and the Extra field's content. 
    • On the second (or more) submission, only the Extra field is added as a comment, and the Occurences counter is increased. The ScoutProject and ScoutArea are ignored. If Extra is empty, only the Occurrences counter is increased, no comments added. 
  • Case (bug) Title is generated from the Description.
    • The first 128 characters of Description will be used for the case title.
    • If the Description length is more than 128 characters, then the title will be the first 124 characters followed by "..." (3 dots), a total of 127 characters.
• Extra
  • Text type of parameter to hold any details (stack trace, operating environment, HTTP headers, or other details about what might have caused the error). Recommended to avoid using it for sensitive 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 be created from this submission (no aggregation).
• ScoutDefaultMessage
  • This is the default text that will be returned by the HTTP post request in case of success. You can use it to validate the success of your submission.
  • If the submission is appended to an existing case, and that case has some text in the Scout Message field, then Scout Message will be returned instead.
• FriendlyResponse
  • Set to “1” or “true” in order to get a response in HTML format. By default, the response will be XML.

Recommended Usage

Based on the above we recommend the following usage:

Back to the top

BugzScout Cases vs Standard Cases

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.
  • This is useful when you want to share custom messages for the submitters: ex when you start investigating the issue, you can set it to “we are investigating the issue,” but you can update it later to “fix identified, working on it" or "this problem is fixed in the next version” and these messages will be sent in the replies of the submissions.
• Scout Will
  • This controls whether or not future submissions that match this case’s Description will be appended to it or not.
  • Stop Reports means that 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 means that future submissions with the same Description will continue to be appended to this case.
  • After 50 occurrences, FogBugz will automatically change this field to Stop Reports. The field will show how many remaining occurrences will be logged.
  • If Stop Reports is set (by you or FogBugz automatically), the occurrence count and last occurrence date and time will still update when new submissions are received.
• Last Occurrence
  • The most recent date and time of a submission. This is always updated on new submissions, regardless of the value of the Scout Will field.

Back to the top

Submitting BugzScout Cases with XML API

You can also submit cases using the FogBugz 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 an API token.

Remarks for Using the API for BugzScout Cases

• Use the new command for all the submissions having the same sScoutDescription. This is needed for the Occurrences and Last Occurrence to be updated correctly. If you use the edit command referencing the ixBug returned at the first submission, the occurrence related updates will not be triggered, and the Occurrences counter will be stuck at 1, even after several updates.
• No change regarding that sScoutDescription will be used by FogBugz to decide whether this is the same BugzScout report and appending is needed, or a new case needs to be created (different sScoutDescription).
• Set the sTitle, at least on the first submission, because it will not be automatically generated from sScoutDescription. If you don't set the sTitle, the title will be set to (Untitled). If you don't want to change the case title in any subsequent submission (because you changed it on the UI), just omit the sTitle parameter from the parameter list.
• Set the sProject. If you don't set it, the case will be opened in the first project on which the current user has Modify permission (current user meaning the user who created the token).

Back to the top