Scarab - User's Guide

Scarab for mere mortals

The Scarab Development Team


Table of Contents

I. What is Scarab?
1. Introduction
What is Scarab ?
How does Scarab differ from other issue-tracking systems ?
Scarab history
Scarab functionality at a glance
Sharing the information and tracking projects
Sharing information in a project
Tracking the health of a project
II. Scarab for everyone
2. Connecting to Scarab
Anonymous access
Logging in
Choosing a module
Logging out
3. Scarab ergonomy
Scarab navigation
Navigation bar
Entry forms
Buttons
Tabs
Results and selection pages
Sort order
Customizing the user interface
4. Entering and managing issues
Entering an issue
5. Searching for issues : queries
The Query bar
Issue ID
Advanced queries
Search the knowledge base
Searching by personnel
Searching by state change
Custom queries
Saved queries
Cross module queries
6. Using Scarab report builder
Selecting issue types
Row and column content
Data types
Sorting attribute options and user attributes into headings and groups
Selecting users and attributes
Reporting by dates
Generating and saving reports
III. Scarab for module administrators
7. Creating and managing modules
Creating a new module
Editing a module
8. Best Practices
Prototype!
Sharing a module with a customer
Use case
A possible solution
9. Workflow
Introduction
BasicWorkflow
State-transition management
Conditions
IV. Advanced topics
10. XML Import/Export
Introduction
XML export of issues
XML export of metadata (issue types, attributes)
XML import
11. Integrating Scarab and other tools
Integrating Scarab in Eclipse
Integrating Scarab in Netbeans
Integrating Scarab and Maven (Maven 1)
Connecting your Maven project and Scarab
Linking the Changes plugin and Scarab
Integrating Scarab in TWiki

Part I. What is Scarab?

Chapter 1. Introduction

What is Scarab ?

Scarab is a highly configurable issue tracking tool that can be used for all types of projects: technical and non-technical alike. Because all parameters in the system are configurable, this tool meets the needs of the project as well as the individual user. Each implementation can be configured directly to the workflow processes of the project through the definition of issue types and attributes. The user interface is designed to be accessible and constant: once you become familiar with the look and feel you will find new processes quick to master.

Scarab provides a robust set of tools for issue management :

  • Issue entry : The issue entry process is designed to help users create meaningful issues and avoid duplication. Attributes are used to describe issues and to check the issue database for similar entries. If any duplicates are found, the user has the opportunity to review potential duplicates, add comments to like issues or modify their issue before committing it to the database.

  • Templates for issue entry : Frequently entered issue criteria can be saved in templates for speedy entry. Files can be attached to an issue, and are tracked directly with their issue. Users can add and edit comments to issues as needed. Users can access and review the complete issue history while viewing an issue.

  • Issue query : Accessing issues in the database is simple using the query feature. Users can easily find, access and modify issues individually or in groups. The advanced query feature allows the user to create detailed issue searches, specifying values for multiple attributes and limiting their search to specific date or issue number ranges. The Custom Query feature allows the user to search by text string-the user can specify a set of information to compare against issues in the database. Frequently used queries can be saved and easily run.

  • Reports : The robust reports interface allows the user to create and save reports. Reports provide customizable and meaningful metrics.

  • Email notifications : As important events occur, email is generated and sent to all parties associated with the event. Alert emails contain links to views of the event.

Scarab is written in Java and based on web technologies. Scarab stores its informations in a database, often MySQL but other databases such as Oracle and PostgreSQL are supported.

How does Scarab differ from other issue-tracking systems ?

Scarab is highly customisable. Scarab has no predefined or hard-coded workflow (that would define what happens as an issue changes from the 'Open' to the 'Closed' status. There are no predefined artefact types (such as bug report, improvement, etc.) You are completely free to define your issue types the way that suits you best. Scarab may be less easy to understand and use at the beginning but you will get a tool that suits your needs better at the end.

Most other issue tracking systems (open-source or commercial) have an issue processing logic that is embedded in the application. This means that you are often caught in the logic defined by these systems. Scarab does not limit you that way.

Scarab history

To stay short, let's say that Scarab was born from the passion of a highly talented developer : Jon Scott Stevens. Jon was a key figure in the Apache Jakarta project, where he played a major role in the Velocity and Turbine projects.

His aim was to design and develop a compelling replacement for Bugzilla.

CollabNet gave him an opportunity to develop this software in open-source — but also to integrate this tool in their collaborative development suite.

Today, CollabNet is no longer the driving force behind the development of Scarab; they left this role to a small team of developers from around the world but continue to provide support and useful advice on certain occasions.

Scarab functionality at a glance

  • A full set of functions such as those found in other issue tracking systems : issue entry, queries, reports, event notification, collaborative accumulation of comments, dependency tracking.

  • On top of these standard functions, Scarab provides an unlimited number of fully configurable modules (your projects), of artefact types (Defect, Improvement request, Requirements,...), of Attributes (Operating system, Status, Priority, etc.), of Attribute options (P1, P2, P3) that can all be defined on a per-module basis, so that any module can be configured for specific needs..

  • Import/Export interface via XML : allows an easy migration from other tracking systems (e.g. Bugzilla).

  • Modular code design: allows manageable modifications of existing and new features over time.

  • Integrated customization UI : Scarab is fully customizable through a set of administrative pages.

  • Easily modifiable UI look and feel.

  • Integration :Scarab can be integrated into larger systems by re-implementing key interfaces.

  • Based on application server technologies :Scarab is built using Java Servlet technology for speed, scalability, maintainability, and ease of installation.

Sharing the information and tracking projects

The success of any project depends on managing and solving problems. How you use the tools will be dependent upon how your project is organized and your planned workflow processes. You can use the tools as a knowledge sharing device and a means of tracking and managing the health of your project.

Sharing information in a project

Information captured within Scarab can be highly effective for many areas within a project. Because Scarab is so highly configurable, knowledge resources can be customized to the needs of each discipline within an organization. Tracking a feature across discipline lines can be done by copying issues and creating dependencies between them.

For instance, Project Go has issue types organized by milestone within the feature lifecycle. Project Go has the following issue types: Planning, Development, Testing, Release management and Support. New features are entered in the Planning issue type where they are processed till ready for development. At that point, the issue is copied to Development, Release management and Testing issue types and all copies are set to blocked by the Development issue. All actors have a full description of the feature, including all conversations involved in creating the specifications. Since all issues have interdependencies, monitoring efforts across the discipline lines is an easy process. Blocking all the issues by the Development issue means that none of them can be closed till the development cycle has completed, but each group can continue to work based on what is happening with the development project. For example, documentation may be a part of the release management cycle. Writers can track the features in development and track their documentation efforts in their own issue with links to the development issue. After the feature has been released to the users, support can track incoming issues and easily access information about the feature through any of the issue types and be able to link to other areas quickly through the issue history.

Tracking the health of a project

Scarab can assist in tracking and assessing the health of a project. If your project is experiencing a particular type of concern you need to track, Scarab can help you do this through a series of processes.

For example, Project Go has just added a new database and developers are concerned that the new database will cause significant performance problems. While running routine reports and queries, the project lead has determined that there is, indeed, a performance issue possibly associated with the new database. It is determined that fixing this problem is top priority and critical to the success of the project. To facilitate work on this problem, the project owner has created an issue entry template and series of queries and reports. Users are asked to use the template and enter specific information about what they have found in a description attribute. The template is used to regularize information about issues. Using a saved query, project members can quickly access issues involving this concern and concentrate efforts in critical areas. Tracking the progress of resolving the performance problems can be done using reports. How to configure it for your needs can be confusing. This document is a suggested set of practices.

Part II. Scarab for everyone

Chapter 2. Connecting to Scarab

Abstract

To use Scarab, after having connected to the URL of your installation using your web browser, you can or must identify yourself. Thereafter, you need to choose the module in which you will work.

Anonymous access

Anonymous access may be granted to certain modules. These modules are listed on the home page of your Scarab installation and you don't have to login to access them.

If you have a Scarab account, or if you can create one, you'll probably able to access other modules, or you'll be able to perform more operations on the modules to which an anonymous access is granted.

Logging in

In a corporate environment, someone may have created your account beforehand and may have given you your Scarab user name and password.

In other situations, or if you do not have a user account, usually you may create one using the "Register" link. In the register process, you will need to use an email address to which you really have access. Otherwise, the whole communication between Scarab and you will not work.

If you forgot your password, you may have it reinitialized using the "Reset password" link. You will then receive a new password by email. During your next connection, after having typed the password you have been sent, you will be asked to change it immediately.

Choosing a module

In the home screen (for anonymous access) or immediately after logging in, you will choose the module in which you plan to work.

You may also ask to access other modules if their manager has configured them so. For this, click the "Ask roles" button.

Note

If you have access to only one module, You are automatically redirected to this module home page after logging in.

This module selection screen would not appear.

Logging out

At the end of your Scarab session, we suggest that you disconnect cleanly, using the link located at the top right of every Scarab screen.

Chapter 3. Scarab ergonomy

Scarab navigation

The Scarabinterface is organized to allow access to all major functionality from anywhere in the application. Each of the action screens provides relevant information along with links to access further details as needed. A unified and consistent interface allows you to easily recognize the types of information and actions available on each screen.

Each screen provides the following navigational aids :

  • The Left navigation bar : The navigation bar is organized by issue type, then by function. To access functionality within a specific issue type, select the title of the issue type on the left navigation bar. The functionality available to that issue type will appear below the title.

  • The Query bar : The query bar provides access to the search tools. The issue ID box allows you to access a specific issue number. The select query box provides access to the Advanced and Custom query features. If you have any saved queries, they will appear in the select query box.

  • Section titles : Most information screens are organized in tabular format. Each section is presented with an informative section header, describing the section and, often, providing general information about the section. Column headers with arrows can be used to change the sort order for that table. For the sort column, the title has an arrow indicating the direction of the sort: the default is ascending. To change the direction of the sort click on the arrow.

  • Buttons : Are used to indicate a set of actions that can be performed. Often you will find more than one set of buttons on a page. Buttons directly below a section will perform actions on the section only, if you have you may find an Update Optionsbutton beside an attribute selector in one section. This indicates that if you change the attribute clicking the button will change the options available to that attribute.

  • Checkboxes : Are used to select list items for modification.

In many cases, helpful information is included directly on the screens to clarify unusual operations. Error messages are provided in line to help identify where the error occurred and specific means for remedy.

Navigation bar

The navigation bar, on the left, helps you navigate in Scarab.

To make an efficient use of screen space, it is possible (since milestone 20) to make the nav bar appear and disappear.

If the navigation bar is visible, you can make it disappear by double clicking somewhere under.

In a similar way, if you need the navigation bar and it is not there, you can make it appear by double clicking in the free space on the left.

Entry forms

Entry forms are easy to use. Default data points are indicated with * (asterisks) beside the field title. Often you will find textual guidelines within the entry forms to help you through the form entry process.

Buttons

Navigational buttons are available on each screen. These buttons perform actions on the data entered in the form. The

  • Cancel cancels the process in which you currently are engaged..

  • Continue button will take you to the next part of the entry process.

  • Done button will save your work and return you to the last process in which you were engaged.

  • Next button indicates that there is further information to be gathered on the next screen. Clicking this button will cache your current data and take you to the next part in the wizard.

Tabs

Some multipart functionality provides tabs for easy navigation between parts. In the reports functionality you can use the tabs to switch from defining row content to the final output characteristics.

If you have a saved data set for an entry form (like saved queries or reports, or issue entry templates), the top section contains a drop down list with all such items available for use on this form. This appears in the issue entry, query and reports functionality. To use a saved form select the one of interest from the drop down box and use the select button to render the selection.

Each attribute in an entry form displays all available options, from which you can select one or more.

Results and selection pages

Results screens appear after you have activated a request, like a query, a report, etc. Each results screen provides a list of items with some descriptive information.

Many results screens allow you to perform actions on the items that appear. Under the items you will find a set of dropdown boxes containing actions that can be performed. The first box allows to export the results in the selected format. The available formats are Excel (.xls) and tab separated values. Once you select the export format from the dropdown box, the results will appear in the browser window in the format selected. You can then save the results locally.

Sort order

Items are initially in ascending order by their ID. To sort by an attribute, click the title of the attribute. The sort will change to ascending by that attribute. Clicking the arrow beside the attribute name will provide a descending sort.

Customizing the user interface

Many screens are customizable. You can add to or remove the attributes that appear on your screen by clicking on the add/remove attributes from view link. Use the check boxes to show or hide attributes. Add a check to the items you would like to appear on your screen. Use this screen to determine the order of the columns by using the "Columnar sequence" field.

Chapter 4. Entering and managing issues

Table of Contents

Entering an issue

Scarab has a very dynamic issue management strategy. Committing, tracking and modifying issues is a simple process. Scarab has the following issue management features :

  • Relations : Scarab can track relationships between issues. Dependencies between issues can be flagged and tracked through either the issue entry process or while reviewing one or multiple issues.

  • Change tracking : All changes made along with information about the user who made the change, when the change was made and any comments committed along with the change are tracked with the issue.

  • Comment viewing and editing: : All comments made to the issue are tracked. Comments allow support or other type conversations to be viewable and editable by any parties interested in the progress of an issue.

  • Save frequently entered information: : The issue entry template feature allows you to create a frequently used set of data points for attributes in a template. When a template is used, the issue entry form is pre-populated and the user can alter information as needed.

Entering an issue

After selecting your issue type and the Enter new link from the left navigation you can enter values for the available attributes. Each attribute will have either a drop down box with options to select from or a text entry form for you to enter text. All attributes with an asterisks (*) beside the title must have values before saving the issue.

If duplication tracking is active, entering an issue becomes a three step process. The first step is to define a subset of attributes that will be used to check for duplicates in the database once you have used the button. The second step is to review all possible duplicates and determine what action to perform (see Duplicates for more information on duplicate management). The third step is to enter values for the remaining attributes.

While you are entering the issue you can attach a relevant file using the same form. Attaching a file helps you and others to easily share relevant information or patches. For more information on adding attachments see Attachments..

Before submitting your issue you can select where in the application you would like to go next. Each option submits the issue and takes you to one of the following functional areas:

  • Assign issue

  • View this issue

  • Start page

  • Return to home

Chapter 5. Searching for issues : queries

Query functionality includes defining a very specific query, using a customized query, using saved queries and accessing specific issue IDs. You can also use the Issue List to access the last query.

  • Know issue number: enter it in "Issue ID" field.

  • Know attribute values for issue: use advanced query

  • Know approximate information about issue: use custom query.

  • Already defined search parameters: use saved queries

For ease of use, frequently used queries can be saved. Use the left navigation link or the query bar to access saved queries.

The Query bar

The query bar provides quick access to frequently used search functionality.

  • If you have any saved queries, they will appear in the drop down box on this bar.

  • The Issue ID form allows you to search the database for a specific issue ID.

  • Advanced query allows you to specify detailed search criteria.

  • Custom query is a text string search feature.

  • Most recent will run the last query or any saved query you have set as a default.

Issue ID

To access a specific issue enter the issue number in the search form and click the Issue ID. If the ID you requested is not found an error message will appear and you can enter a different ID.

Accessing issues across projects requires the following information:

  • permission to view issues in the target project

  • short name of the target project

  • issue number

For instance, jdoe is in the games (gam) project and wants to view an issue from the interface (int) project. Jdoe can enter INT1 and click the Issue ID button to view the first issue in the Interface project.

If you do not have permission to view issues in the target project you will receive an error message. Likewise, if you enter an invalid project ID or issue number an error message will be generated.

Advanced queries

The advanced query form provides an interface for you to unambiguously define your search criteria. You can use this form to enter values for some, all or none of the attributes available in your issue type. You can further qualify your search criteria by requesting issues within a particular number range or date range. Say you want to know all closed issues relating to the AIX operating system within the last week. You can enter a date range (use the MM/DD/YYYY format, for instance, 01/01/2002) and define specific values for the operating system and status attributes. Click option from the Select query list on the query bar. Clicking the Submit button will run the query.

You can define values for some, none or all of the attributes. Scarab will search the knowledge base for issues that contain all of the values you have specified. The advanced query form allows you to define fine grained search criteria. There are three types of search criteria available on the advanced query form:

  • Search the knowledge base

  • Searching by personnel

  • Searching by state change

You can use each of these sections individually or a combination to qualify your searches. If you run a query without defining any attributes all issues associated with the logged in user ID will be returned.

Search the knowledge base

The Search the knowledge base. section provides a space for you to define values for issue attributes. Each attribute that is available to your issue type is represented here. You can define values for all, some or none of the issue attributes. You can also limit your search to a range of issues or creation dates. .

Once the issue is submitted, the database will be searched for issues containing the values for all of the attributes defined in your search criteria. To effectively find the issues you are most interested in you want to define only the attributes that will meet your criteria. If you define attributes outside of your requirements you will be less likely to find any issues that meet your criteria. For instance, jdoe is looking for issues involving database errors affecting one of the UNIX operating systems. Rather than defining a value for the operating system, jdoe can create a search that will search for text strings about the database errors. If jdoe needs to refine the search criteria further, other attributes can be defined. When defining your search criteria, you should start with the smallest set of characteristics relevant to your needs.

Searching by personnel

The Searching by personnel section allows you to search for issues based on users associated. Depending on what user attributes have been defined, you can search by the commitor and/or the assignee. All users that are associated with issues in the issue can be selected from a user attribute in this section. You can select as many users as you need.

Searching by state change

This field allows you to set an attribute you would like to monitor and the original value and expected new value. For instance, you may want to know all issues that have changed from a low severity to a high severity. Additionally, you can monitor these changes within a date range. For example, you may be interested in knowing which issues have changed severity within the last week. Clicking the "Update options" button saves your changes to the query. You can also set your results view preferences at this time. When the view preference is based on Issue state or status, the sort order is not necessarily alphabetical. It mirrors the order for the attribute which is determined by an administrator. You can alter the search order and the number of issues that appear per page. You can submit your query at this time or choose to save it.

Custom queries

Custom queries allow you to search the database based on a refined set of parameters. You can search on any of the text attributes as well as any other attribute your project owner has included as a quick search parameter.

For this section, select the attributes you would like to search against then enter a search string. Each attribute will be searched for every term that appears in your search string. For instance, the Game project has the Summary, Description, Story-line and Error message string attributes. You are interested in any issue that involves the usage of a joystick. You can select one, some or all of the text attributes and then enter "joystick" in the search string. Once the search is initiated, all entries in the attributes you have chosen will be searched for the term "joystick".

You can use this form to determine how you would like the search results displayed. You can select what attribute you would like the results ordered by as well as the number of issues you would like to see per page.

Saved queries

Once you have a well defined set of search parameters you may want to save them for future use. Saved queries can be used to generate reminders, keep you informed of progress on issues or to quickly access a specific issue configuration. You may have access to globally available saved queries or create your own.

Saving queries

To create a saved query access the Advanced queries page and define your search parameters (for more information see Advanced). Click the Save this query button. Stored queries are accessible through the Saved queries link on the left navigation bar or in the drop down box on the query bar. The saved query drop box only appears if you have stored queries.

The Save this request screen is where you can give your saved query a unique identifier. Your query name should be short and descriptive. The Saved query name appears in the Query bar. You can add a description to further identify your query. The query description appears in the saved query list screen and can help users make a better determination of which query to use.

For example, you have defined several queries that search for issues that relate to the AIX operating system. One of your queries specifically look for all new high priority issues entered. A second query may search for all closed high priority issues. The first query is named AIXopen, the second AIXclosed. You can use the description field to remind yourself that these issues are specifically for high priority issues.

Before you can save your query you need to determine the availability. Your query can be available only to yourself by selecting "personal" from the drop down list. If you think your query is of value to all members of the project, you can select "global." If you do not have permission to create a global saved query, the query will be submitted to the administrator for approval (see Approval for further information on the approval process).

Click the Save button to complete the saving process.

Managing saved queries

The Stored query page is used to manage the saved queries. All queries that are available for this issue type appear in this table. Click on the name of the query to access the query edit screen. The location link will execute the query. Clicking on the name in the Initiated by field will provide an email form, using your browsers default email interface. You can also set a default query and subscribe (see below for more information).

You can use the buttons to affect multiple queries simultaneously. Use the checkboxes to select the queries you would like to affect.

  • The Copy button will create a copy of the query. You can click the name of the copy to edit. Using this feature can help you to create fine grained saved queries.

  • The Remove button will remove the saved query from your list. You can delete any of your personal saved queries.

Cross module queries

Cross module queries allow you to search multiple modules or issue types or both in a single query. Upon accessing Scarab from the navigation bar, you can click on the Build cross module query tab. On this tab, you can either select a previously saved cross module query, or create a new one.

The Projects / issue in this domain table lists all issue types in all modules available to be added to your query. Projects are only available if you have permissions that allow you to query in that module. Add issue types to your query by checking the checkbox in the Select column and clicking the Add selected button. This will move the selected issue types to the Build list of issue types section. You can remove all issue types from you query by clicking the Remove all button or remove only selected issue types by clicking the Remove selected button.

Once you have selected all of the issue types you want included in your query, you can save the list for future use by clicking the Save button. You must then complete the Name field and click the Save button again.

To begin you query, click the Define query button. This will take you to the Advanced query page where you can define your query criteria as you would for a single module query. For details on building queries, see Advanced query.

Chapter 6. Using Scarab report builder

Scarab allows you to build reports to provide snapshot status reviews of issue activity. You can tailor the reports to fit your specific needs by defining which data types are included and selecting the output format. The report data types can include attributes and options, users, and dates. The report can be formatted for the web browser, Excel (.xls), or as a tab separated list (.txt). You can define reports to include a single or multiple issue types in a single or multiple modules.

To access Scarab reports:

  • Select module in which you want to start defining the report.
  • Click on the Reports link. This will take you to the Saved reports list page. You can select a previously saved report, or you can build a new report.
  • Select the report you wish to run by clicking on the report name, or access the report builder by clicking the Create new button.

The Scarab report build consists of three tabs: The Report information tab allows you to define the scope of the report and enter summary information. The summary information is for saving reports. There are two sections on this tab: Artifact types selected for this report, and Summary.

Selecting issue types

The issue type included in the report defaults to the currently selected issue type. If you wish to define a report for a different or multiple issue types/modules, click the Edit list button. This will take you to the Cross module/issue type list page. You can use this page to define a list of issues types within the current module or across multiple modules to be included in your report. It is highly recommended that the issue types for the report be chosen prior to working with the content tabs. Though it is possible to modify the list later, additions that conflict with already entered data on the other tabs will not be allowed.

On the Cross module/issue type list page, you can perform the following tasks:

  • Select a previously saved cross module list to use.

  • Remove issue types from your report by checking the checkbook next to any issue type in the top section of the page and clicking the Remove selected button. To remove all issue types, click the Remove all button.

  • Add issue types to your report by checking the checkbox next to any issue type in the top section of the page and clicking the Add selected button.

  • When you have selected the desired group of issue types for your report, you can save the list for future use by clicking the Save button.

  • Click the Done button to return to the Report information page where the selected issue types will appear in the Artifact types selected for this report section.

Entering Summary information

The Summary section of the Report information tab allows you to enter information for saving your report. This information is optional and can be added at any point report creation process. You can provide the following information:

  • Enter a name for your report in the Name field.

  • Enter a description in the Report description field.

  • Select the report Availability. If you have permissions that allow you to make your reports available to other module members, the Availability field will appear allowing you to choose whether to save the report for personal use or for module use.

  • Select the format for the report. The available formats are Web, Excel (.xls), and Tab separated (.txt).

When you have entered all of the desired information, click the Update button to add this information to your report.

Row and column content

The Row content and Column content tabs allow you to define and organize the data included in your report. These tabs contain identical information and options; however, you can select different data types on each tab. This allows you to create unique, in depth reports. Once both the row and column content have been defined, you can generate the report.

Data types

The Row/Column criteria section allows you to select the type of data presented in the rows or columns of your report. The available selections are:

  • Attribut(s) / option(s) When this data type is selected, you can choose from among the attributes and options defined for the selected issue types.

  • Utilisateurs (par attribut utilisateur)When this data type is selected, you can choose from among the module members and specify a user attribute for each user selected.

  • Date(s) When this data type is selected, you can define dates for each row or column of your report.

The option selected in the Select content type field determines the data available in the rest of the sections of these tabs. Only one content type can be used for each heading. If you choose Date(s) as a content type on either the Row content or Column content tab, it must be the only heading on that axis. However, you can define user criteria for one or more heading levels and option attributes for other headings on the same axis. Changing the content type to Date(s) after defining a set of user or attribute/option criteria for either the row or column content tabs will discard the previously entered data for that tab.

Sorting attribute options and user attributes into headings and groups

When generating reports containing attribute options and user attributes, the organization of the data can mean the difference between a useful analysis tool and an unreadable mass of numbers. To help you organize your data, Scarab allows you to arrange report data into headings which are combined in the final report to allow multiple criteria per cell.

Headings are defined solely by the data they contain. To create headings within your report:

  1. In the Report builder, click on either the Row content tab or the Column content tab.

  2. Select the content type for this heading in the Select content type drop down box.

  3. Select the options you wish to include in the first heading of your report.

  4. Click the Update button.

  5. If you wish to include more than one heading in your report, in the axis content: Row/Column headings section, click the Add another heading button.

  6. Select the content type for this heading in the Select content type drop down box. If the previously defined heading contains user attributes or attributes/options, you cannot select the Date(s) content types. Doing so will discard the previously entered heading.

  7. Select the options you wish to include in this heading.

  8. When finished, click the Update button.

  9. Continue adding headings and selecting options in this manner until all the options you wish to see in your report have been included.

You can edit a previously defined heading by clicking on the radio button next to the heading and clicking the Edit selected heading button. You can delete previously defined heading by clicking on the radio button next to the heading and clicking the Remove selected heading button.

Scarab allows you to further organize reports data by grouping the attributes and options within your headings. For example, if options P1, P2, P3, and P4 for the Priority attribute have all been selected, you could group P1 and P2 as "high priority" and P3 and P4 as "low priority".

You must have defined at least one heading containing Attribute/option(s) in your report before you can define groups. To group options within headings:

  1. DOn the Row content tab or the Column content tab, select a heading containing the Attribute/option(s) content type and click the Edit selected heading button.

  2. In the group related data section, enter a name for the group and click the Add new button. Repeat this step if you wish to have additional groups within this heading.

  3. In the Grouping report data-set attributes/options section, select the group you want each option to appear in from the Group name drop down box next to each attribute/option.

  4. When done, click the Update button.

Selecting users and attributes

Reporting on user attributes allows you to determine how the workload in your module is distributed. You can use the Users (by attribute) data type to create reports that indicate how issues are assigned or otherwise associated with users.

To define Users (by attribute) reporting criteria:

  1. On either the Row content or Column content tab, select User (by attribute) from the Select content type drop down box.

  2. In the Users table, select the checkbox in the Select column and the desired user attribute in the drop down box in the Association column of the user you wish to include.

  3. Click the Add selected to assignee list button.

To include multiple user attributes for a single user, you must add the user again with the additional attribute selected. For instance, if you wanted to generate a report to indicate which users have ownership and quality assurance responsibility for the issues in your module, you would need to select each user twice--first with the Assigned to user attribute, then with the QA contact user attribute.

Reporting by dates

To help you determine how your module is progressing, Scarab allows you generate reports based on dates/times. Date/time reports provide a snapshot of issue activity at a single point in time. You can design reports to include several date/times to show the progress over a specific period of time.

To create date/time reports:

  1. On either the Row content or Column content tab, Select Date(s) from the Select content type drop down box.

  2. In the Select row/column (dates) content table, use the drop down boxes to select the date and time you want to include in your report.

  3. Click the Add single date/time button.

  4. Continue adding dates in this fashion until all desired dates are included.

You can include future dates in your report. A row or column with a future date will appear blank in the generated report; however, the row or column will populate when the report is regenerated after the date has passed. This can be used to create progress reports which are generated repeatedly. By adding dates well into the future and saving the report, you can minimize the amount of time spent defining frequently generated reports.

Generating and saving reports

Once you have defined both row and column content, the Generate report button will appear. Clicking this button will create the report in the format you have selected on the Report information tab.

When viewing the report in the Web format, you can perform the following tasks:

  1. Rotate the report by clicking the swap row and column link.

  2. Save the report by clicking the Save this report button. If you have not entered summary information on the Report information tab, you will be returned to that tab. You must enter a name for the report and click the Update button to add the summary information to the report. Click the Save this report button again to save.

  3. Export the report to Excel or tab separated values by selecting the desired export format from the Export results to: drop down box.

Part III. Scarab for module administrators

Chapter 7. Creating and managing modules

Creating a new module

From the home page, choose any module, if you have not done that already (creation of a new module cannot occur outside a context, but that is irrelevant with the task we want to perform).

From a module home page, or from many other pages, you can reach the module administration functions, but you may need to double-click in the left margin to make the menu appear.

From there, choose Modules, Manage modules and push the Create new button.

You may now enter the information about the module that you want to create.

Two fields are worth a particular attention.

The Parent module determines at this time the module which will be used as a template, a model, for the module you are about to create. Basically this means that the new module will "inherit" all Issue types and attributes from the parent module you choose.

Caution

This "inheritance" occurs once and for all at the time of module creation. Issue types and attributes are copied from the parent to the new modules.

Modifications to the issue types and attributes of the parent module you choose now will not be propagated to the new module afterwards.

To say it yet another way, issue types and attributes are copied from the parent to the new module, not shared between them.

The module parent will also appear in the modules lists. For instance, the Source module which has Pacman JVM as parent appears as such in the list:

You can change the parent later (see next Section) if you want to change the display logic but that should not be the main reason of your parent module choice at creation time.

Editing a module

To edit the definition and properties of a module, choose Manage modules in the Admin menu, then choose the module.

The next screen is pretty self-explanatory.

You cannot delete a module but you can mark it as deleted. The module will no longer appear in the modules lists (though it will still appear, as deleted, in the Manage modules list if you ever want to recall it someday later).

Chapter 8. Best Practices

Prototype!

From the previous chapter, you should have understood that it is not easy (at the moment?) to spread "schema" modifications (changes in issue types, attributes, etc.) towards a large number of modules.

If you begin to use Scarab and you plan to create a significant number of modules, it is very important to design the initial schema from which the modules will be created.

A bit of advice: do not neglect the initial design phase at the beginning of the "Scarab project". Which artefacts will be useful for you? Which attributes will you use? What is your workflow (see next chapter)?

Make a prototype! Even if you have a "production" installation of Scarab around (or you are creating it), make another database instance and test your design. Do you think what you have imagined will meet your needs and those of your (future) users?

Sharing a module with a customer

Use case

Your Scarab installation is open to your customers, at least partly (the customer has access to certain modules). You want to allow your customer to enter defects or modification requests but you do not want him/her to see neither all the internal issue processing in your organization nor the technical comments or the procedure. How to achieve this? In Scarab, you cannot show or hide attributes according to the Role, for instance.

A possible solution

Use two different modules.

The first one has all the attributes the customer may enter and see (you may name this moduler "Customer access"): description, priority, severity, environment, etc.

The second one has usually more attributes; it contains most attributes in the first module plus technical attributes related to the internal processing.

How do you make this work then?

When the customer enters an issue, this issue must be processed by someone in your organization.

Tip

To make sure someone reads all customer issues (without having to connect periodically to Scarab and execute a query), think of putting or addind his/her email address to the module Archive email, so that he/she receives an email for all issues entered or modified.

The customer request is evaluated, maybe edited, discussed... and may sometimes never find its way to further processing: misunderstood features may be explained, evolutions may be rejected by the customer in a commercial deal, etc.

If the request must be processed by the organization and creates one or several tasks, the issue is copied to the second module and you may then create a dependency between the original issue and the one corresponding to the internal task. When the task is ended, it is closed in the internal module and may then be closed in the "Customer access" module. The customer is automatically informed that the processing of his/her request is ended.

Chapter 9. Workflow

Introduction

Workflow has been a widely debated concept for the life of Scarab. In the lighter part of what's been called "workflow" there is the enforcement of certain conditions on the issues, based on the value of its attributes, its so called "state", or other conditions. In a deeper understanding of the term, workflow deals with the integration between the Scarab actions and other systems/processes.

Scarab supports pluggable workflows. Until the milestone 19, the default workflow was not to have one. In fact there was a default workflow that did nothing and allowed all transitions. From milestone 20 upwards, the default option is to use a simple workflow called 'BasicWorkflow'; the behaviour of this workflow is explained below.

Changing workflow

If you want to change workflow to use another one or design your own, read the Workflow chapter in the Scarab Developer's Guide.

BasicWorkflow

The functionalities now provided apply to the first, lighter meaning of the term Workflow.

State-transition management

The concept of "state" of an issue in Scarab is usually binded to one (or more) attributes. Any attribute of "dropdown list" type may be considered to hold an "state" for the issue it belongs to. In some way this is equally true for the rest of attribute types, but dropdown lists are better suited for this, because they have a closed set of values defined.

Though this has always been possible in Scarab, the lack of transition-restriction between the different states made it too easy to get confused, because Scarab did nothing to enforce the workflow processes defined.

With the basic workflow functionalities, you can define a workflow of state-transitions on a dropdown list attribute, allowing you to set from which value can you change to any other, and which Rol should the user have to perform the change.

This way, any given user will get the options of the status holder attribute limited to the values to which he can make the transition, based on the current value of the attribute, and on his Roles.

Definition of transitions

The transitions should be defined globally, so you will have to get a user with administration permissions, and go the the "Administration - Global Data - Global Attributes" screen.

Now, choose the attribute on which you want to define transitions, or create a new one. Remember: it must be of "dropdown list" type.

In the bottom of the screen, you will notice a section called "Transitions", with a first line with the "New" label. As long as there are no other lines, there are no transitions defined for this attribute, and it will behave just like any other dropdown list attribute.

If you want to define any transition, you will choose the "from" value, the "to", and the required role to make this transition, and click on the "Save" button. If you want to delete a transition, check its selected checkbox, and click on "Delete"

Note that as soon as you define any transition on the attribute, the 'default' free-transition behaviour will be disabled. If you want other transitions allowed for any role, you will have to explicitly define them.

If you need a initial state, you will have to define a transition from "Empty Option" to its value. If you need an always available state, you will have to define a transition from "Any Option" to its value.

Conditions

Conditions are intended to allow the administrator of Scarab to make some behaviours conditional. As of b20, conditions are defined selecting one or more values from the dropdown-list attributes. The condition will eval to true for a given issue if _any_ of the selected values is set in this issue.

You can apply conditions on two behaviours:

  • Requireness of an attribute (globally or module-scoped)
  • State-transitions

In the first case, the admin can force any attribute being required whenever the condition evals to true. In the second, a conditioned transition will only be enabled if the condition evals to true.

In both cases, you will notice a button with the text "Edit Conditions". Once clicked, you will get a screen in which you can select the values from every dropdown-list attribute that will form the condition. Clicking "Done" you will be back on the previous screen, and will be able to read the defined condition.

Part IV. Advanced topics

Chapter 10. XML Import/Export

Introduction

Scarab allows module administrators to:

  • export

    • issues of a module (data);
    • issue types and attributes of a module (metadata);
  • import

    • data to update or create issues in a module.

In the current development of Scarab it is not possible (yet) to import the metadata, i.e. issue types and attributes.

XML export of issues

[This section to be written.]

XML export of metadata (issue types, attributes)

[This section to be written.]

XML import

[This section to be written.]

Chapter 11. Integrating Scarab and other tools

Integrating Scarab in Eclipse

An interesting way to bring Scarab information into Eclipse is probably to use an RSS reader, for example Eclipse RSS Reader. Let us use this plugin as an example.

You can keep an eye on a given issue or on the result of any public query (except for multi-module queries). Say you want to keep an eye on the history of the PACS1 issue in Scarab. In the bottom right corner of the issue page in Scarab, you have RSS and ATOM links.

Copy the URL in the RSS link.

Now, in Eclipse, create a new RSS channel.

Paste the issue RSS feed URL and click "Load".

There is only one translator available for this feed format, so you may proceed.

Now you must choose a project and a file name for your RSS feed.

The RSS appears now among your project resources in the Package Explorer.

When you click the feed, you get a new window with the history. The "Browse" link brings you back to Scarab in the issue page.

Integrating Scarab in Netbeans

Abstract

A NetBeans plugin allows to include Scarab issues in the to-do list.

This plug-in (.nbm) is currently available from the NetBeans tracker at this URL: http://tasklist.netbeans.org/issues/show_bug.cgi?id=69572

Integrating Scarab and Maven (Maven 1)

Connecting your Maven project and Scarab

As you probably know, you can fill in the Scarab URL in the POM of your project.

To do this, you need to add the entity to your project.xml file:

<issueTrackingUrl>http://192.168.0.151:8888/scarab/</issueTrackingUrl>

This will create a link to Scarab in the Project Info part of your Maven-generated project site:

Linking the Changes plugin and Scarab

You can go a step further and connect now your changes, as detailed in the ./xdocs/changes.xml file, and Maven issues.

Add this to your build.properties file:

# For the changes plugin
maven.changes.issue.template=%URL%/issues/id/%ISSUE%	      
	      

Now you can create links from your changes (in changes.xml) to Scarab. Example:

	        
    <release version="1.22" date="2006-02-01">
      <action dev="jean-francois.elfouly" type="fix" issue="VDCO134">
        Modified FaringServicesBean to fix a bug related to the faring in city pairs where
        the departure date determines the season.
      </action>
      <action dev="jean-francois.elfouly" type="add" issue="VDCO135">
        Modified FaringServicesBean to add a faring rule for fare bases with specified
        travel dates (inbound, outbound or both).
      </action>            
    </release>
	        
	      

will create nicely formatted links in the generated changes-report.html page:

Integrating Scarab in TWiki

Abstract

Use an RSS feed with TWiki for Status and Progress Reporting

TWiki is an enterprise collaboration platform and has a plugin for showing the content of RSS and Atom feeds (HeadlinesPlugin). The results can be formatted as a table. This can be used to show the results of a public Scarab query. Use this, for example, to create a TWiki topic that shows all the Defects that are currently at Status of Assigned. You could even create a table to list which issues were changed to a Status of Resolved in the current month.

  1. Create a public query that finds the issues you want to report. For example, search for all issues with Status equal to Assigned or Reopened. Use a public query so that TWiki will be able to get a feed from it without needing to provide credentials. Alternatively you must include private credentials as part of the feed URL.

  2. Run the query from the Advanced query pull-down list. Verify that the query reports what you expect.

  3. Use your browser to copy the address of the RSS or Atom feed for this query. You would normally do this by right-clicking on the feed name at the top (and bottom) of the query results table.

  4. On a TWiki topic, use the %HEADLINES% variable to pull the feed into the topic.

    %HEADLINES{ href="http://www.saxess.de/testscarab/issues/curmodule/1/tqk/0/template/RSSDataExport.vm/feedType/QueryFeed/queryId/10000/userId/1/type/rss_2.0" refresh="1" header="| *$title* | *$description* |" format="$t| [[$link] [$title]] | $description |" }%

You will see a formatted table of the query results, just as Scarab showed them.

The first column shows the issue name and the second column shows the Status, Summary and AssignedTo attribute values. The entries in the first column also link to the original issue in Scarab.

Beware that the headlines plugin will cache its results to avoid excessive loading on the feed source. The default refresh timeout is 60 minutes. In the example above, the refresh parameter is used to set the refresh time to only one minute.