What is it?
BugzScout is a simple API which allows you to send new bugs directly to Manuscript 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 Manuscript 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 Manuscript 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 feature requests straight into Manuscript.
The URL of this API is http://your.manuscript.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 Manuscript account.
Who will use it?
Any Manuscript user
How is it used?
The scoutSubmit.asp endpoint expects an HTTP Post request with the following values:
The full name of the Manuscript user the case creation or edit should be made as. We recommend using a Virtual User for this.
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.
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.
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 Manuscript, 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 Manuscript. 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:
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.
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.
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.
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.”
Set to “1” or “true” in order to get a response in HTML format. By default, the response will be XML.
Related Article: Bugs handled within Manuscript