1. Installation
   1. What are all these JDOM exceptions ?
   2. Why do I get a NullPointerException on startup ?
   3. Why won't Ozibug initialize and run under Tomcat with the Security Manager configured ?
   4. Why do I get returned to the login page after logging in ?
   5. Why won't Ozibug initialize and run under Sun ONE AppServer 7 ?
   6. Why do I get a NamingException on database configuration ?
   7. Why won't Ozibug initialize and run under JRun 4 ?
2. Internationalization
   1. How do the language pack and locales work ?
   2. Why are multi-byte characters not handled correctly ?
   3. How do I include non-ascii characters in an Ozibug URL request ?
3. Appearance
   1. Why are my fonts big and bold ?
   2. Changing preferences like colour doesn't always work ?
4. Operation
   1. Why am I still getting mail even though I have notification turned off ?
   2. How can a custom category be allowed to accept null/empty values ?
   3. How can I track the time spent on bug fixing per customer ?
   4. How can I configure automatic notifications ?
5. Reporting
   1. What do the XML hyperlinks do ?

1. The context parameter system.properties.filename in the file OZIBUG_HOME/WEB-INF/web.xml file must be set to the absolute filename of the ozibug.properties file (Note: this is not necessary in later versions of Ozibug.) An example is included below.

   <context-param>
     <param-name>
       system.properties.filename
     </param-name>
     <param-value>
       C:/ozibug/WEB-INF/ozibug.properties
     </param-value>
   </context-param>

2. The tomcat.policy file must contain read access for the property system.properties.filename (again this is not necessary in later Ozibug versions.)
3. Testing has shown that a bug in the Tomcat application also means that read access to the property os.name must also be granted.
4. Read, write and delete access must be granted for the servlet context directory.
5. Connect access is necessary for the smtp notifications to be sent.

The following example shows the section of the tomcat.policy file necessary for Ozibug. This example assumes that ozibug has been installed in C:/ozibug directory.

grant codeBase "file:C:/ozibug/-" {
  permission java.util.PropertyPermission
    "system.properties.filename", "read";
  permission java.util.PropertyPermission
    "os.name", "read";
  permission java.io.FilePermission
    "C:\\ozibug\\-", "read,write,delete";
  permission java.net.SocketPermission
    "mail.tortuga.com.au:25", "connect";
};
                      

This problem has been seen when the Ozibug servlet context name contains restricted URI characters, as described in RFC 2396. In particular, the problem was caused when the Ozibug distribution was downloaded by Microsoft Internet Explorer which by default saved the file as ozibug.x[1].x.x.zip, this in turn was unzipped to ../webapps/ozibug.x[1].x.x/WEB-INF/web.xml.

When navigating to the Ozibug URL different browsers handle the context name in different ways. Some browsers (Mozilla, Netscape 7) always URL encode the context name (eg., to ozibug-1%5B1%5D.4.0), while others (Internet Explorer, Netscape 4.7, Opera) only encode the name if the URL is not fully qualified (eg., if only http://localhost:8080/ozibug-1[1].4.0 has been specified). Browsers always seem to store the Ozibug session cookie using the unencoded context name, which may or may not match the the Ozibug URL. If a match does not occur, then the Ozibug session cookie is not sent back to the Ozibug servlet and hence it appears as though there is no active session, causing the login page to be redisplayed.

There is no apparent way to control this behaviour which can in fact be further complicated by different behaviour of the servlet container that Ozibug is running under. So the solution is to simply use a context name that contains no restricted characters.

1. Read, write and delete access must be granted for the servlet context directory.
2. Connect access is necessary for the smtp notifications to be sent.

The following example shows the section of the server.policy file necessary for Ozibug. This section should be placed at the end of the file. This example assumes that Ozibug has been installed in C:\SunAppServer7\domains\domain1\server1\applications\j2ee-modules\ozibug_1 directory.

grant codeBase "file:C:/Sun/AppServer7/domains/domain1/server1/applications/j2ee-modules/ozibug_1/-" {
  permission java.io.FilePermission
    "C:\\Sun\\AppServer7\\domains\\domain1\\server1\\applications\\j2ee-modules\\ozibug_1\\-", "read,write,delete";
  permission java.net.SocketPermission
    "mail.tortuga.com.au:25", "connect";
};
                      

<jvm-options>-Djava.security.policy=C:/Sun/AppServer7/domains/domain1/server1/config/server.policy</jvm-options>
                      

This problem occurs because of the class loading algorithm employed by JRun and a backwards/forwards compatibility issue introduced by the latest JDOM release.

To overcome these problems simply place the jdom.jar and log4j-1.2.6.jar jars from OZIBUG_HOME/WEB-INF/lib into the JRUN_HOME/servers/lib directory.

An Ozibug locale is defined by a set of three property files which are located in the .../ozibug/WEB-INF/classes directory. The files messages_XX.properties, audit_XX.properties and exceptions_XX.properties define the resources for the locale XX.

The locale is either specified by the client browser in the request or by the Ozibug application (configured by the default.language and default.country properties in the .../ozibug/WEB-INF/ozibug.properties file.)

The files messages.properties, audit.properties and exceptions.properties define the resources to use when NO locale is specified.

The property files can be zipped up into a jar file and then the jar can be put in the .../ozibug/WEB-INF/lib directory. This is optional.

• To add a locale to Ozibug you simply need to place the new property files in the .../ozibug/WEB-INF/classes directory (you will also need to restart Ozibug.) The locale will be used when specified in a request by a client browser.
• Change the default.language and default.country properties in the .../ozibug/WEB-INF/ozibug.properties file to change the application locale.
• When operating in a single locale the reference data is specified in the file .../ozibug/WEB-INF/reference.xml file. This data can be changed (or localized) through the reference data screens by a system administrator.
• When operating in a multi locale mode you may require reference data to be localized for users in different locales. This can be done by updating properties specified in the I18N section at the end of the messages.properties file. Note that when you define these properties they override the reference data definitions that can be seen by the administrator.

Some servlet containers (notably Orion 1.5.2 and WebLogic 6.0sp2) do not correctly translate multi-byte characters when running on a Windows platform (specifically when the system property file.encoding is Cp1252). Ozibug 1.3.0 and later ships with the necessary configuration to handle the known cases, the details of which are outlined below.

• Orion 1.5.2. The distribution includes a Orion specific configuration file ../ozibug/WEB-INF/orion-web.xml that sets the default character set to UTF-8. On deployment the contents of this file is merged with ORION_HOME/application-deployments/default/ozibug/orion-web.xml (in a standard Orion installation).
• WebLogic 6.0sp2. The distribution includes a WebLogic specific entry in the configuration file ../ozibug/WEB-INF/web.xml to treat all incoming data as UTF-8. Refer to WebLogic 6.0 Documentation for further information.
• WebLogic 6.1. The distribution includes a WebLogic specific configuration file ../ozibug/WEB-INF/weblogic.xml that treats all incoming data as UTF-8. Refer to WebLogic 6.1 Documentation for further information.

When constructing an Ozibug URL request such as that used for running a report, special care is needed if non-ascii characters (eg., accented characters or multi-byte characters such as Japanese) are to form part of the URL.

Most browsers allow pasting of such characters into the location bar and will perform the necessary character conversion to generate a valid URL. However, the conversion performed is dependent on the character and the browser. Most browsers convert single byte characters (eg., ä) into a single byte Unicode character representation (technically an invalid conversion), whereas multi-byte characters are converted into UTF-8 (Opera being a notable exception converting to UTF-8 in both cases).

Servlet containers that operate with a single character set of UTF-8 (either through configuration as above, or design) cannot handle the single byte Unicode character representations and generally ignore these unknown characters and those following it. The containers that have been seen to fall into this category are Orion 2.0.2, WebLogic 6.0, Jetty 4.0.2 and WebSphere 4.0.1. The solution is to manually translate these characters into UTF-8, for example ä would be represented by %C3%A4.

More information on the subject can found on the Jetty web site.

1. Login to Ozibug as an administrator and create a new custom field of type fixed list.

   This is done by selecting the -- NEW -- option of the Select reference category pull down list. Enter the category as "Customer" and the type as "fixed list". Tick the modules that you wish these fields to apply to. Now add the values of the list, which will be each customer names, eg. "Customer 1", "Customer 2", etc.

   Hint: You may want to add an "Internal" or "None" value for those bugs not entered by a customer.

2. Create another custom field of type free format. This will be used to add in the time spent on each bug. Enter the category as "Correction time (minutes)", the type as free format and tick the checkboxes of the modules that you wish this field to apply to (the same as above.)

3. Logout as the administrator. The new fields will now be shown when creating, editing or displaying bugs in the modules that you assigned them to.

4. Now comes the hard work - you must edit each bug and assign the correct values to each field for the customer and the time spent to correct it.

5. Now you are ready to generate a report based on including the time and customer field and sorted on the customer.

   Select the report screen from the icon at the top of the page, then from this page select the required module from the Module pull down list, located in the top left corner underneath the page header. Now select the fields you require in the report by ticking the associated checkbox fields at the left side of the table, this must include the Correction time field. Select the Customer field to sort on by ticking its checkbox on the right hand side of its entry on the screen.

   At the bottom of the reports screen select the type of the report to be CSV (detail) (comma separated values.) You can now generate the report by pressing the Apply button.

6. Your browser will prompt you to save the data to a local file. Do this and then import the file into your favourite spreadsheet application.

7. You can now use your spreadsheet functions to sum the Correction time fields for each customer and produce a total.

   Hint: You can also use your spreadsheet functions to post process the data, such as correcting any malformed data items, or perhaps resorting the rows and columns.

Automatic email notifications are configured through the ozibug.properties file.

• One or more properties of the following format can be specified to send email notifications automatically when a bug is first created.

  #
  # notifications.new.x.y
  #
  # Where x is the module name  (can be * for all modules)
  #       y is the bug priority (can be * for all priorities)
  #

  So for example, the following property

  notifications.new.*.* = email_address_1, email_address_2

  Will send notifications to the email addresses specified for all new bugs

  notifications.new.Ozi_Bug.critical = nobody@nowhere.com

  Will send notifications to nobody@nowhere.com for all new critical bugs in the module "Ozi Bug", notice the conversion of the space character to an underscore character.

• One or more properties of the following format can be specified to send email notifications automatically when a bug is updated, note that you will get a notification for each change to a bug with the specified combination of module, status and priority.

  #
  # notifications.updated.x.y.z
  #
  # Where x is the module name  (can be * for all modules)
  #       y is the bug status   (can be * for all status)
  #       z is the bug priority (can be * for all priorities)
  #

  So for example, the following property

  notifications.updated.*.closed.* = email_address_1, email_address_2

  Will send notifications to the email addresses specified for all updates to bugs with a closed status.

  notifications.updated.Ozi_Bug.closed.critical = party_on@nowhere.com

  Will send notifications to party_on@nowhere.com for all closed critical bugs in the module "Ozi Bug", notice the conversion of the space character to an underscore character.