Ladies and Gentlemen, The Beetle!

Whatever the size of your project, the chore of managing issues - bugs, feature requests, even programming assignments - can be aided by a good issue tracking system (ITS). One of the newest tracking systems is Scarab. Easy-to-install, easy-to-use, and built to be customized, Scarab may give scaly, old Bugzilla the boot.

Your software has issues. And they need to be dealt with. And whatever the size of your project, the task of managing issues — bugs, feature requests, even assignments — can be aided by a good issue tracking system (ITS).

The most common ITS in the open source world is the venerable Bugzilla, but that doesn’t mean it’s your only choice. One of the young, capable upstarts is Scarab (http://scarab.tigris.org). Scarab is powerful and very flexible, and unlike some other issue tracking systems, it isn’t specifically designed for tracking defects. Instead, everything in Scarab is configurable, and its modular construction allows for future growth and customization.

Although Scarab is still only in beta, it is rapidly maturing. Is it ready for production use on your project, though? Let’s find out.

Scarab has a couple of prerequisites that you must install first. Foremost is a relational database. Scarab supports a number of different databases, including PostgreSQL and Oracle, but if you have a choice, MySQL is highly recommended, because that database has been tested extensively. (The rest of these installation instructions assume you’re using MySQL, but you can find additional information specific to a number of other databases in the documentation on Scarab’s web site.)

Scarab is implemented in Java, so it requires a Java SDK, a Java virtual machine, and the ever-popular Ant build system. It also requires a Java servlet engine to run, but there’s no need to install one separately if you don’t want to. Scarab comes packaged with a stripped-down version of Tomcat that’s sufficient to run Scarab.

You can download the latest version of Scarab from http://scarab.tigris.org, or grab the bleeding edge version from their CVS repository.

The instructions in this article are based on version 1.0-beta19. Scarab is still a beta application and under heavy development, so you should read the install instructions included with the distribution if a newer version has been released or if you’re installing from CVS.

Scarab requires several environment variables to be set, before it can be properly built. ANT_HOME and MYSQL_HOME should be set to point to the directories where the respective packages are installed. If you installed these packages as part of your distribution, that directory is likely /usr.

Similarly, JAVA_HOME should point to the directory where Java is installed, probably something like /opt/java/jdk-1.4/ or /usr/java/jdk-1.4/. The final important environment variable to set is your java CLASSPATH. If you have a version of the Apache Xerces XML libraries installed on your system (especially version 2.x), it is important that your CLASSPATH not point to the Xerces JAR files when you build Scarab.

Next, you need to create a file to store custom build settings. First cd scarab/build and create a file named build. properties. Then, add the following lines to the file:


scarab.user.firstname=Admin’s first name
scarab.user.lastname=Admin’s last name


scarab.site.name=My Personal Issue System

What do all of those lines mean? The first two are the username and password that Scarab should use when logging into the database. Unless your database is completely unprotected by a password, they are required.

The next four lines configure administrator access. You can also use the scarab.user.password property to set the administrator’s initial password, but it may be easier to take the default and then change it later using the Scarab interface, because the build.properties file requires you to encrypt the password first (using what looks to be an MD5 hash).

The third and final set of parameters are optional, but fairly useful. scarab.http.domain sets the domain that Scarab uses for web page links in update emails, and scarab. email.domain sets the domain used to automatically assign email addresses to users based on their username. Finally, the scarab.site.name property is simply used to give a name to the site at the top of the page and in your browser’s titlebar.

Now that you have all of your build options set up, it’s time to actually build the software. This step is easy. Just change directory to scarab/build and run ant. When Scarab is done building, the only step left is to install the database. This is accomplished by running the create-db script located in the src/sql directory. Here’s a summary of the process:

$ cd scarab/build
$ ant
… lots of compiling output …
$ cd ../src/sql
$ ./create-db.sh -u scarab –password

That’s it. Scarab should now be built and ready to run. Go to the tomcat/bin directory at the top level of the Scarab build tree and run the startup.sh script. It launches Scarab’s built-in Tomcat server and sets everything up to run. You may have to set the scripts in the tomcat/bin directory to be executable with chmod u+x *.sh before things will run, as in:

$ cd tomcat/bin
$ chmod u+x *.sh
$ ./startup.sh

Administering Scarab

Once Scarab is running, all interaction is performed through a web browser. To connect, you just have to point your browser to http://myserver.com:8080/scarab/issues.

The first page you should see is a login page, where you can log in using the administrator username that you previously set in the build.properties above. The default initial password for the administrator is set to 1.

Figure One: The main Scarab navigation area

On the left hand side of the Scarab screen, there are three boxes (shown in Figure One) that contain links to different sections of Scarab. The three sections contain, respectively, standard user items, administrator items, and a help section with a number of topics.

If you’d like, you can change the default administrator’s password by clicking on the Users section under the list of “Admin” options.

To understand how Scarab tracks issues, the first thing to learn is its two-tiered system of categorizing issues. Each issue entered into Scarab falls within an issue type and a module. Issue types categorize different classes of issues and define a set of attributes that can be attached to that issue. Modules are a larger classification of issues and define a set of issue types that can be used for individual issues in the module. Although Scarab is flexible enough to allow a myriad of ways to make use of modules and issue types to organize issues, the most common methodology is to have a different module for each project that you want to track and issue types for the various types of issues those projects may have.

For example, you might want to have one issue type for bugs, another for features that you’d like to add, and a third for tracking the submission of code patches from people who don’t yet have permission to commit directly to CVS.

One of the great strengths of Scarab is its flexibility, and the core of that flexibility lies in the customization of issue types. Each issue type that you create can have an arbitrary number of attributes associated with it.

Attributes come in two flavors: attributes and user attributes. Attributes represent data that the user can enter about an issue, such as a description or current status. Attributes can be in the form of strings, dates, integers, or options selected from a drop-down box. User attributes represent different users that are associated with the issue (and receive email when it changes). For instance, you might have an “Assigned to” user attribute, and a “Quality assurance engineer” user attribute.

Scarab also allows you to give different users differing levels of permission to view and edit issues. Scarab has the concept of roles. Each role can be set to allow the user to perform a variety of different tasks within Scarab, such as viewing issues, editing issues, or creating new issue types. When a user attempts to access a module for the first time, Scarab prompts them to choose the role that they wish to have with that particular module. That role can either be assigned automatically, or it can require approval by a designated, authorized user (this behavior is configurable on a per-role basis).

Entering New Issues

There are a couple of different ways to enter new issues in Scarab. When you first log into the system, you’ll land on a page that lists the currently available modules. Click on the module that you want to work with to see a list of issue types associated with that module. From there, you can enter a new issue by clicking on one of the issue types in the list.

You’ll notice, though, that in the upper left corner, there’s also a link labeled Enter new issue. This always takes you back to the current page to allow you to select a new issue type and enter an issue.

After you enter your first issue for the current session, a second link is added below Enter new issue, allowing you to skip the list of issue types and go directly to entering a new issue of the same type as the issue that you most recently entered.

After you’ve selected an issue type for your new issue, Scarab starts to lead you through the process of filling in all of the attributes for the issue. Attributes for an issue can be grouped into attribute groups, which are displayed with a header giving the title of the group. When you start to enter the issue, though, all of the attribute groups for the issue type may not be displayed immediately. Scarab has the ability to attempt to identify duplicate issues before they’ve been completely entered. If the issue type you’re entering has been configured to do this duplicate checking, you’ll be presented with just the first few attribute groups. Fill them in with the appropriate information, and then click Next.

Figure Two: Entering an issue in Scarab

When you click Next, Scarab searches the database of previously entered issues, and tries to pick out any that might be duplicates. If it finds any, it shows the list of possible duplicates. At that point, you can either select one of the existing issues and add a comment to it, or click on Continue entry to enter in the rest of the attributes for the issue. Figure Two shows a new defect being entered for the Pacman JVM module.

In addition to filling in data for the attributes associated with an issue, you can also attach files. These files can be of any type, and Scarab even stores the MIME type of the file. To attach a file, you simply click on the Choose file button in the “Attachments” section of the issue creation page and select the file to attach. Be sure to add a description of the file you are attaching and select the type of the file you’re adding (or tell Scarab to try to figure it out on its own).

When you’re done entering attributes, click on Done. Scarab advances to the user attributes page, where your next step is to assign users to the different user attributes associated with the issue type. At the bottom of the page, you’ll see a list of registered users. Select one or more by clicking the checkbox to the left of each name. You can then select what user attribute you want to use to associate with that user by selecting it from the dropdown box on the right side of the user entry.

When you’re done, click Add selected to assignee list to add the users to the list of assigned users towards the top of the page. When you’ve finished assigning all of the users you want, make sure you click on the Done button or the assignments won’t be committed to the issue.

And you’re finished. The issue has been entered.

Querying Existing Issues

Scarab has a powerful system for querying issues, letting you create complex searches based on various attributes. In addition to standard queries, such as keyword and data ranges, Scarab can use complex patterns to search on a text attribute and can find issues based on how recently the value of a certain field has changed (and what it’s changed to or from). Scarab also allows you to save your queries, and can output to a web page, an Excel document, or a tab-separated text file.

A handy query to save is one that shows what open issues are currently assigned to you. Using the default modules and issue types that Scarab includes in the default build, let’s create a query that shows you all of your currently open defect issues in the “Pacman JVM” sample project.

First, log into Scarab and select the “Pacman JVM” module. Then, select New query from the “New and saved queries…” dropdown menu near the top of the page. On the page that appears next, check the box next to “Defect” and click Define query.

Figure Three: Advanced Query Definition

(If you’re taken to the shorter “Custom Query” page, click on the Advanced Query link on the right hand side near the top. If the header already says “Advanced Query”, you’re ready to go.) The page should look similar to Figure Three. Scroll down through the advanced query page, until you get to the “Status” attribute. In the list of attribute options, select everything except “Closed.” Then scroll down to the “Personnel association search.” Type your username into the box, select “Assigned to:” from the “Association” drop down menu and click Add new. Now scroll down to the bottom of the page and select Save this query.

On the “Save query” page, enter a name for your query, and select “personal” availability. Personal availability makes the query visible only to you. On the other hand, if you choose “module” availability instead, anyone who has access to the module can run your saved query.

A handy tip when you’re setting up the modules and issue types that you’ll be using for your own projects is to make sure that all issue types in every module have a status attribute. Since Scarab only lets you query on attributes that are common to all of the modules/issue types that you are querying, this lets you search across all of your issues to see which ones still need attention.

Viewing and Modifying Issues

Issues can be viewed either by following a link to them (in a query result list or in an email, for example) or by typing the issue ID into the text box at the top of the Scarab page.

When an issue is shown, it’s divided into several different pages that can be reached from tabs at the top of the issue. If your role for this issue has the proper permissions, you can also submit modifications to the issue. These can be attributes, user attributes, comments added to the issue, or attachments.

Whenever a modification is made to an issue, Scarab sends an email describing the changes to the user submitting the change, the user who originally created the issue, and any other users that are associated with the issue via a “user attribute.” The email includes the text that describes the reason for the change, as well as a summary of the attributes that were modified and a link that allows the recipient to go directly to that issue in the Scarab system.

Scarab can also generate statistical reports on the issues that exist in the system. It allows you to generate a report similarly to a query, which can then be displayed on the web page or exported to an Excel or text format.

To create a new report, click on the Reports link in the “Issue tracking home” box in the upper left corner. Select Create new. Let’s create a report for the “Pacman JVM” module that shows a breakdown of completed defect issues by type of resolution.

To start, check the “Defect” checkbox and click Done. Then, enter a name for the report and click Update. This takes you to the “Row content” section, where you can select the fields to include in the rows of the report.

For your report, select the “Resolved” and “Closed” values for the “Status” attribute, followed by “Update.” Once the row content’s been selected, click on the Column content tab near the top of the page and select all of the values in the “Resolution” attribute. When you click Update, Scarab adds buttons near the top to either save the report or generate it. If you click on Generate report, you should see a report that shows the number of completed issues that fall into the different resolution categories.


In Scarab, templates allow you to pre-generate part of an issue to make it easier and faster to generate similar issues. This feature can be used to save time for a commonly entered issue, such as a new bug report, or it can be used to make it easier for other users to create issues.

Let’s create a new defect template for the “Pacman JVM” module that you can use when entering new issues that are Linux-specific. Start by selecting Edit templates from the “Issue tracking home” box. When the next page comes up, select “Defect” from the dropdown list, and click on Create new. From the “Save template” page, enter a name for the template, then select “Linux” from the “Operating System” attribute.

It’d also be nice to not have to check “New” in the status attribute every time you create a new Linux defect, so scroll down and select “New” in the “Status” attribute. Once these are selected, click Save. Now, when you enter a new defect issue, Scarab will offer a list of the available templates to choose from. Simply select your newly created template and Scarab fills in the data from the template for you.

Issues Solved

Scarab is a full-featured, flexible system for tracking issues. Is Scarab ready for production use, though? Once it’s up and running, it seems to be very stable. The Scarab project itself has been using Scarab to track their own issues for over a year now, without any data loss. Scarab can help you keep track of all of your issues. And it’s cheaper than therapy.

How Does Scarab Measure Up?

Scarab is a reasonably mature and stable system, but how does it measure up to the big boys? Two large, popular, and very mature packages are Bugzilla and RT: Request Tracker.


Bugzilla is the 800-pound gorilla in open source bug tracking. It (or a variation of it) is used by many of the largest open source projects. It’s very stable and has a long history of usage. There’s little question that it’s capable of handling huge volumes of issues.

The comfort of such a huge track record does come at a price, though. Bugzilla is not a flexible system. The attributes associated with an issue are fixed. You can customize the values that can be associated with those fields, but that’s about it. If your software or development process doesn’t fit with the methodologies that Bugzilla is designed for, Bugzilla can be an awkward, even clumsy fit.

Scarab’s flexible paradigm for issue types and modules makes it easy to customize the system to the needs of an individual project. With relatively little work, a Scarab administrator can have a working, customized system with an interface that looks and feels much cleaner than Bugzilla.


RT isn’t as well known as Bugzilla, but it’s an equally large and mature project. It’s designed to be a system for managing tickets, which could be issues in a software development project or requests submitted to a help desk. Interaction with RT is handled via email, which can be used easily by people who don’t know any more than how to send email.

RT is designed to be “enterprise-grade” and it shows. Its feature list is large — large enough that it is probably overkill for most open source software development projects. Issue tracking systems like Bugzilla and Scarab can be set up fairly easily by a single person working in their spare time. RT is tailored for groups where there is a dedicated administrator for the tracking system.

For projects that don’t require RT’s more powerful features, Scarab is a simpler alternative. It can be set up fairly quickly and doesn’t require a lot of maintenance once it works. Individual users can also do a lot of the maintenance for different modules. You won’t need an additional person to manage Scarab.

William Nagel is the chief software engineer for Stage Logic, a small development company that primarily uses Linux. He can be reached at bill@stagelogic.com.

Comments are closed.