Hosted Bug Tracking and Project Management System

Create Account | Sign In

WebSubmit Guide

What is Web Submit?

Web Submit is a very powerful service that allows bugs to be submitted from your own Web site directly into your project at BugHost. You can easily customize the forms, fields, and requirements for creating Web pages on your Web site. You can quickly get your customers submitting bugs by using the built-in HTML code generator which generates HTML code to put in your Web page. Very little work is required by your Webmaster, but there are a few things that your Web developers should be aware of.

How does Web Submit work?

You must first configure your project to allow Web Submit functionality. Each project requires a user license in order to use this feature. Once a Web user is created, you can easily create the necessary HTML code that is required for your Web site.

Once you post the HTML code to a page on your Web site, your users can enter bug information which gets sent directly to BugHost.com into your project. The information in the Web page is formatted in a specific way to tell BugHost what information to put in each field. Once the bug is reported, BugHost records it and directs your user back to your Web site to a URL that you specify. The user is unaware of the transfer from your Web site to BugHost and back again.

Setting up a Web User

We made it easy to configure your project to accept bug reports from Web users. You must have at lease one user license available for each project you wish to create a Web user for. After you create a project, select your project from the Admin list, fill out the name of your Web user, and click Create Now. You will be able to change the user name and return URL after you create the Web user.

Web User

The Web User name is used to identify bugs submitted by Web users. It will show up in the Submitted By field for each bug that was submitted by a Web User. The Web User is a special user account which has very little security rights. You cannot log in to the system with this user account, but bugs will be submitted through a special login ID rather than an email address. This ID will be generated automatically by the BugHost system and cannot be changed. This special user account information cannot be edited through the regular administrative menu.

Creating HTML Code

BugHost will help you create the basic HTML code to put in your own Web page. The code that is generated is placed within a table to make it easier to place within your Web page. Each field and field input is assigned a class name to allow you to configure a style sheet, if you so desire. These class names will be ignored by Web browsers if you are not using a style sheet.

To generate code, you must first configure the fields that you would like to place on your Web page. There are some fields which produce drop-down list boxes on your page while others are text-based. You are not limited to using these fields the way that BugHost configures them. The code generator configures the fields to be one or the other, depending on how it is within the system. If you prefer to use a drop-down instead of a text box, you will have to change the HTML code to do this. BugHost generates drop-down boxes for Application, Bug Type, Severity, Priority, Status and Assigned To and generates text boxes for Reported By, Summary, Description, Found In Version, and To Be Fixed In Version. What shows up in the drop-down boxes is determined by the Internal and External options for each of those fields. Only items marked as External Only (or Internal and External) will be populated in these fields.

You can modify the HTML code to display drop-down boxes rather than text boxes if you want to restrict your users' input to a pre-defined value. For instance, you can set the "Found In Version" field to display a drop-down by changing the following:

Original BugHost code:
<tr class=bhRow>
	  <td class=bhFieldRequired>Found In Version *</td>
	  <td class=bhFieldInput>
		    <input name=x_FoundInVersion size=10 maxlength=10 class=bhTextBox>
	  </td>
</tr>
Modified code to use a drop-down:
<tr class=bhRow>
	  <td class=bhFieldRequired>Found In Version *</td>
	  <td class=bhFieldInput>
		    <select name=x_FoundInVersion class=bhDropDown>
			      <option value="1.0">Version 1.0</option>
			      <option value="2.0">Version 2.0</option>
		    </select>
	  </td>
</tr>

Fields

Not all fields are available for Web Submit. For instance, it does not make sense to say that a bug is fixed when it is submitted, so this field is not available for Web Submit. The following is a list of fields and field names that you can use for Web Submit. Note that these fields can be generated automatically, so it is not vital to remember these when creating your Web page.

Field HTML Field Name
Reported By x_ReportedBy
Application x_Application
Module x_Module
Summary x_Summary
Description x_Description
Operating System* x_OS
Found In Version x_FoundInVersion
To Be Fixed In Version x_ToBeFixedInVersion
Type of Bug x_BugType
Category x_Category
Severity x_Severity
Priority x_Priority
Status x_Status
Assigned To x_AssignedTo
Notes x_Notes

Of course, you can label the fields to anything you like on your own Web page. For instance, you may decide to have a field that says "Steps required to reproduce" instead of "Description". You will have to decide what fields get mapped to the ones in your BugHost project.

* Note: The OS field is a multi-select field and allows for more than one item to be selected. By default the code generator uses check boxes to allow the user to check the operating systems the bug applies to. The Web Submit processor will look for multiple fields with the name x_OS and apply the value for each field with this name.

Field parameters

Do not change any of the field parameters that BugHost generates, such as textbox maxlength or drop-down values. If any of these values are changed, the field will be ignored. For instance, each Application you create in your BugHost project has a unique number (ID) assigned to it. If you have 3 applications, the only valid ID's might be 1, 2, and 3. If you change it to 4, the field will not be accepted and will attempt to use the default value instead. Likewise, allowing text placed in text fields to be longer than the values BugHost generates will also cause the field value to fail and be truncated.

Reported By

It is sometimes desireable to respond to a customer after they provide input about your products. We recommend using the Reported By field to capture your customer's email address. You can ask for their name or any other information in this field, but is may be useful to have their email address if you need to contact them after receiving the bug.

Notes

If there is extra information you wish to collect from your users but do not have a field for, you can add notes to each bug report by using an input field with the name x_Notes. Every field that has this name will append an additional note to the bug. For instance, if you have a field called "Additional Comments" and "Computer Hardware", you can add the following code to your Web page:

<tr class=bhRow>
  <td class=bhFieldRequired>Additional Comments*</td>
  <td class=bhFieldInput>
    <textarea name=x_Notes class=bhTextArea cols=60 rows=10></textarea>
  </td>
</tr>

<tr class=bhRow>
  <td class=bhFieldRequired>Computer Hardware *</td>
  <td class=bhFieldInput>
    <textarea name=x_Notes class=bhTextArea cols=60 rows=10>Additional Computer Hardware:</textarea>
  </td>
</tr>

Whenever a bug is submitted, it will contain a note (if filled out) with the information that was provided. You are able to use a variety of input types as long as the field name is x_Notes. For instance, you may decide to use a SELECT input value for a drop down box that will place the contents of the item into the notes field.

Return to URL

The Return to URL field allows you to specify what the user will see after the bug is submitted. Once BugHost receives the bug information and records it, it will direct the user back to the URL you specify here. This is useful for saying thank you to your customer or perhaps generating an email.

Combining multiple projects in one Web Page

You may wish to have all your different projects listed in one Web page for your user to fill out. This can get a bit tricky, but is possible if you plan it right.

Each project has its own login ID, so you could easily combine them into one drop-down box using the login value for each. By default, BugHost creates the login value as a hidden field which the Web submit processor uses to determine which project to post the bug into. It does not generate code for all projects at the same time, so you would need to find the Web Submit ID for each and put them into a drop-down list, like this (substitute your own ID):

<select name=x_Login class=bhDropDown>
  <option value=123456789>Widgets</option>
  <option value=987654321>Sprockets</option>
</select>

The potential problem with doing this, however, is making sure that all values for your drop-downs are the same for each ID. Since each project has its own set of fields and field values (ID's), it is possible that you will have a scenario like the following (the ID's are in parenthesis):

Project 1: Widgets
Bug Types: Unrecoverable (1), Data Loss (2), Nitpick (3)
Severities: High (1), Medium (2), Low (3)

Project 2: Sprockets
Bug Types: Crash (1), GUI (2), Security (3)
Severities: Low (1), Medium (2), High (3)

As you can see, the values for project 1 are not going to display the same values for project 2. For example, if the user picks project 1 from the drop-down, you would need to have some fancy scripting on your Web page to display the proper values for Bug Types and Severities. Or perhaps you could create multiple pages depending on what value they pick. Another option would be to have the same values for all projects, but this would require that you had the values syncronized as well. In the example above, project 1 has the value of 1 for High severity and a value of 3 for High in project 2. If the user picks High, it will only have one value associated with it (1, for instance). If the user picked project 2, viewing the bug report would indicate that the severity is Low because project 2 has Low as ID 1. You can see the value of these drop-down items in the Admin menu by looking at the status bar when putting your mouse pointer over each item in your Web browser.

Configuring the Web Submit Form

By default, users will not be able to submit any bugs until you have configured the Web Submit form. Do this by clicking on Forms in the Admin menu. You will need to decide what fields you want to show up, which ones are required, and what value to default to if it is not supplied.

If you want to set a value every time a new bug is submitted but not have the user choose it, you can make a field required but not show it. Just select the default value and BugHost will automatically set the field when the new bug is processed. For example, let's say that you wanted to have all bugs submitted by Web users have a status of "Needs Review". Here are the steps to follow:

1) Create a Status called "Needs Review" and make it available to External Users
2) Configure the Web Submit Form to require this field
3) Make sure that the field is not shown to the user
4) Select "Needs Review" for the default value
5) Update the form and generate the code

Of course, you would need to make sure all other fields are configured the way you want them before generating the HTML code.

Secure connection

You may wish to use a secure connection for submitting bugs to BugHost through Web Submit. By default, the code that gets generated does not make it a secure connection. This is because when the bug is submitted via a secure connection, returning the user to a non-secure Web page will display a warning by the Web browser. If you want to use a secure connection, you should also have a secure return URL. This will prevent the warning dialog from appearing.

To set a secure connection, change the line in the HTML code:

<form name=frmSubmit ACTION=http://www.bughost.com/websubmit.asp METHOD=POST>

to the following:

<form name=frmSubmit ACTION=https://www.bughost.com/websubmit.asp METHOD=POST>

Using the https: protocol will ensure a securely encrypted transfer to your BugHost project.

Required Fields and Field validation

Enforcement of required fields is done with scripting in Javascript, by default. If a user leaves a required field blank and clicks on the Submit button, the Web browser has client-side scripting to inform the user. If the user's browser does not support scripting, this error will not be displayed. The BugHost Web Submit processor does not enforce the fields to be set, but rather it uses the default value if the field data is not supplied. This is to prevent the user from knowing that the transaction is taking place off of your company's Web site. If you need to ensure that the user filled out all required fields before submitting, you may wish to have your own validation of the fields on a separate page before sending them on to BugHost.

Style Sheets

Style sheets allow Web developers to easily create a standard look-and-feel for their Web pages. Style sheets are fairly easy to implement, but require some knowledge of how to do it. This is beyond the scope of this document, but we have provided a guide to what styles we assign when creating the HTML code.

Field Usage
bhrow Table Row
bhField Table column which has a field label
bhFieldRequired Table column which has a required field label
bhFieldInput Table column which has the input field
bhTextBox A text box that is displayed as the input field
bhDropDown A drop-down that is displayed as the input field
bhTextArea A large text box that is displayed as the input field
bhButton A Web page button

Notifications

One useful feature of BugHost is the ability to receive email notifications. This is especially useful when combining it with Web Submit. There are many possible choices to receive notifications when a bug is submitted via Web Submit. We have provided a couple of examples for you below. Anyone can receive notifications for these bugs, but designing a strategy to have them go to the correct people is essential. Note that notifications enforce security, so users who do not have access to view certain fields will not be able to see the information provided. Here are some examples of how to use notifications for Web Submit:

Example 1:
Set up a status specifically for external users called "Needs Review". Then subscribe to the notification for when the status changes to "Needs Review."

Example 2:
Have all bugs that are submitted go to a specific person by requiring the field, not displaying it to the user, and setting the default value. This person can subscribe to the notification "...when a bug is assigned to me"

Example 3:
Subscribe to bugs that are submitted. Any new bug that comes through Web Submit will be marked as submitted by the Web user name you chose when you set up Web Submit.

Disabling Web Submit

If you no longer wish to receive input from your customers, or need to free up a user license, you can disable the Web Submit feature by editing the project you wish to disable and clicking on "Discontinue". The user license will now be available. Be sure to remove the Web page that you created for your customers as well. Any bug submitted via Web Submit will be ignored if the feature is disabled.