Scarab - User's Guide
Contents
1. Table of Contents 2 Connecting to Scarabs seieren dere ecl Ree Tee ms Ere EE PN Ies e ERE ESEESE 13 Anonymous ACCESS oE E nR as EEE IE EPSA 13 EOP SING AN to EE 13 Choosing a module ertian re Sah Cos e edo Eee he pe ud 13 tem 13 3 SCarab erBonomy veo i ERR EUER 14 Scarab navigation sose e o EET eck erem oet eee rumen eet ea 14 Navigation Dar sor eed eve e ep ee RE REE Eo D S e ERR 14 Enty DI III 14 nu AE 15 EL EE 15 Results and selection pages Heer 15 SOM Order docente vies gees RR REP ER UR REEF EP mere ss 15 Customizing the user interface sss Hee 15 4 Entering and managing issues sneri III eene hene ent entree nnne 16 Entering an ISSUE iir or ter Red Pr voee vane eaves Tutors Ceo o dene 16 5 Searching for issues queries ence ence IH eee meminit entrent iS 17 The Query rere 17 Issue TD ESSO NR NO ee doo e UE greed 17 Advanced queries E 18 Search by attribute msosi EOE OEE TEAKS EEEE Ee 18 Searching by personnel 5 1 2 tette ET 18 Searching by state change ssssssss eee 18 Custom QUETIES 19 Saved queries eet ey set ipiis eR e eere gebe eie sre cerae ee Prep eds 19 How to an illustrated five minute tutorial on using2. 33 State transition management eme heme hene 33 Conditions oe reve tee OR ente ep Ped 34 11 Display an informational message Hee 35 IV Advanced topics ote e Dr eed tn ce bad a debtor ede ped 36 12 X ME Import EPO t ao c teer teneat erre eere PER LESE Ee Ore pl ete ges EE Pope Y DES Pp Nuus 38 Introd ction seo HEURE M 38 XML export of ISSUES pssi rore re oh theo pes PO Pe REA T Te keep SE saatoes yas Perdu des 38 XML export of metadata issue types attributes see 38 AML 38 13 Integrating Scarab and other tools ssss 39 Integrating Scarab in Eclipse 39 Integrating Scarab in Netbeans sese 39 Integrating Scarab and Maven Maven 1 39 Connecting your Maven project and Scarab 39 Linking the Changes plugin and Scarab eee 39 Integrating Scarab in TWiki mem mmn 40 Part What is Scarab Table of Contents T Introduction eei tei RI IN RI EINE EUR 8 What 15 Scarab iei err eerte EEEE RE EE S STEE PESER VENEER Pane 8 How does Scarab differ from other issue tracking systems 8 Scarab e P e
3. This plug in nbm is currently available from the NetBeans tracker at this URL ht tp 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 39 Integrating Scarab and other tools 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 ISSU oe Now you can create links from your changes in changes xm1 to Scarab Example release version 1 22 date 2006 02 01 action dev 2 jean francois elfouly type fix issue VDCO134 gt Modified FaringServicesBean to fix a bug related to the faring in city pai the departure date determines the season lt action gt action dev jean francois elfouly type add issue VDCO135 gt Modified FaringServicesBean to add a faring rule for fare bases with speci travel dates inbound outbound or both lt action gt lt release gt will create ni
4. Creating and managing modules sss Herne 28 Creating a new module oit erret rte iret rere rao E ERES S EREE rers 28 Editing a Modules Get oet ete desti Des ERE 28 8 Manage users and permissions in Scarab ee 29 Vniirir E 29 Creatine Users o e e rte reo ovt e PEE RE HERE 29 Edit Usets etie ot e pet ie tr steer tite 29 Creating Roles eR eos ae een 29 Managing User dr preti tette reto TEREE e 30 9 BeSt Practices NAHE 31 Prototype scsi etre tata ep get tote esa bot ais EE e ERE RES E SE OE 31 Sharing a module with a customer 2 0 0 0 cece cece cece cece ee 31 Use CaSO eese LS tated svete RP E e EPIS Pierre 31 A possible solution E 31 10 Wr OW 5er ee eU E WR reda IR He PRIOR WR erem A 33 IntrOdUCtOD 3e operose terr tede Pro voe eror eher AE Ceo tosh dese ordeo 33 Basic WorktloW 5 5 cioe Tee Oa ene Het pee p eei eves eee ed 33 State transition management eH emere 33 Conditions coo UE e Oeo re Ee dts eese bate 34 11 Display an informational message essere 35 27 Chapter 7 Creating and managing modules Creating a new module From the home page choose any module if you have not done that already The creation of a new mod ule cannot occur outside a context From a module home page or fro
5. 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 at tribute 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 mor
6. delete user Creating Roles e Goto the section for roles in navigation for administrators Here you are able to edit create or delete roles For creating a new role you have to use the button for add create a new role e If you want to create a new role you only have to enter a name first Afterwards click Save to con tinue You will be guided to a new screen where you have to choose one ore more permission for your newly created role Every user with this role will have these permission e Save your settings The screen for overview of roles should show your new role for selection 29 Manage users and permissions in Scarab e Editing a role is very similar The name of a role is not editable Managing User Roles Goto the section for user s in navigation for administrators and select a specfic user by user s search e After you have selected a user you can edit the roles for the user by using the related button e Select a role for all modules the user should have any permissions and save your settings 30 Chapter 9 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
7. E RC eU ORE ace bed Dees 9 Scarab functionality at a glance sse meme 9 Sharing the information and tracking projects 9 Sharing information in a project HH 9 Tracking the health of a project HH 10 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 com ments 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
8. 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 Oth erwise 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 13 Chapter 3 Scarab ergonomy Scarab navigation The Scarabinterface is organized to allow access to all major functionality from anywhere in the applica tion Each of the action screens provides relevant information along with links to access further details as needed A unified and consistent interface allo
9. and defining simple queries 20 Cross module queries ice ore etre rex op ee uet Dese eve derer exuta 21 6 Using Scarab report builder cece cece HH e m e mee rene 22 Selectng ISSUE LY PES iesu petuo ieri dots 22 Row and column content Hm emere ree 23 Data ertet e Pro eere bre ronde T ERE eer ERR 23 Sorting attribute options and user attributes into headings and groups 23 Selecting users and attributes 2 0 0 0 cece cence cece ae m 24 Reporting by dates cie E EE EEE EESE EES 25 Generating and saving reports eco herir rette ESEP Ee PETER pers 25 12 Chapter 2 Connecting to Scarab 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
10. 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 Attribute s Option s When this data type is selected you can choose from among the attributes and options defined for the selected issue types e Users for user attributes 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 Date Range 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 sec tions of these tabs Only one content type can be used for each heading If you choose Date s Date Range s as a content type on either the Row content or Column content tab it must be the only con tent type on that axis However you can define different criteria for one or more heading levels on the same axis Changing the content type after defining a set for either the row or column content tabs will discard the previously entered data for that tab Sorting attribute options and user attributes into head ings and groups When generating re
11. 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 24 Using Scarab report builder 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 at tribute 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 Date Range s from the Select content type drop down box 2 In the Select row column dates content table use the calendar to select the date and time you want to include in your report 3 Cli
12. 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 17 Searching for issues queries 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 given format and define specific values for the operating sys tem 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
13. 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 custom er in a commercial deal etc If the request must be processed by the organization and creates one or several tasks the issue is copied 31 Best Practices to the second module and you may then create a dependency between the original issue and the one cor responding 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 32 Chapter 10 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 mile
14. 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 Introduction 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 Velo city 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 e A full set of functions such as those found in other issue tracking systems issue entry queries re ports event notification collaborative accumulation of comments dependency tr
15. on the approval process Click the Save button to complete the saving process Managing saved queries 19 Searching for issues queries The Stored query page is used to manage the saved queries 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 How to an illustrated five minute tutorial on using and defining simple queries Let s use and then save simple queries to display all issues and all new issues in a given module This short example use the Sample data that you may have loaded or not when you installed Scarab other wise it is quite simple to use your own data instead In the nav bar click Public queries Right now you probably haven t any defined query Click Create new No
16. Scarab User s Guide Scarab for mere mortals The Scarab Development Team Scarab User s Guide Scarab for mortals The Scarab Development Team Table of Contents Scarab e Ee ze REC Y IE E URP ER ENTERS 6 1 Introduction i eret te teer Petr nente Ra eee P rete rete cules REO sass 8 What is Scarab 7 sete te loeo teet oe oet 8 How does Scarab differ from other issue tracking systems 8 Scarab histOEy is sich duals dees ven dee seen ert mer ent dood youn de a R Qhd e e sane e 9 Scarab functionality at a glance sss ee He mene 9 Sharing the information and tracking projects sse 9 Sharing information in a project HH e 9 Tracking the health of a project HH 10 I Scarab for everyone ct ee ete petente rea rte ve dota TES Peb Eye ceri cr Apre ede ds 11 2 Connecting to Scarab 2 tete ttr REI Re ERE RR Se TEES 13 ANODYMOUS ACCESS m 13 TOSSING AN use Roe etr MER metere Ie EP i indes 13 Choosing a module 1 ere steer epe nier veri eb Ege ee Prep ge dd 13 OUL o o e CERE oe Roe Nor E UE tp S 13 3 Scarab erBonOmy cese cie ose tenore Ree eR Re Py eene se FE Ue gere fete soe pe tuse see pens 14 Scarab Navigation io nie UU eese te save Mab sen
17. 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 cre ating 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 Introduction 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 cop les are set to blocked by the Development issue actors have a full description of the feature includ ing 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 Develop ment 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 develop ment 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 a
18. acking Ontop of these standard functions Scarab provides an unlimited number of fully configurable mod ules 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 e Import Export interface via XML allows an easy migration from other tracking systems e g Bug zilla e 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 e Easily modifiable UI look and feel Integration Scarab can be integrated into larger systems by re implementing key interfaces e 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
19. 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 com ments 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 Custom er 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
20. be the module owner to do this otherwise it will require an approbation Click Save and you re done The application may have brought you back to the list of private queries the default at this point so if you don t see the query you have just defined just click Public queries again The query you have defined now appears in the query nav bar drop down list 20 Searching for issues queries Now suppose you wanted a list of all new issues instead To define this query click Define query in the grid as we have done before Now scroll down the page and find Status in the Common attrib utes section Common attributes because the query is defined across different issue types since we checked in the grid Select New in the list the lists support multiple selection if you want to group different status in the same query Simply fill the required information to save the query and click Save That s all your new query has been saved 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 permis
21. cely formatted links in the generated changes report html page Integrating Scarab in TWiki 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 creden tials as part of the feed URL 2 Run the query from the Advanced query pull down list Verify that the query reports what you ex pect 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 TWiki topic use the 7 HEADLINES variable to pull the feed into the topic HEADLINES 40 Integrating Scarab and other tools href http www saxess de testscarab issues curmodule 1
22. ck the Add 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 fre quently 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 informa tion 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 25 Part Ill Scarab for module administrators Table of Contents 7
23. dmin 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 28 Chapter 8 users permissions in Scarab Administrator Each Scarab installation has a global administrator His her login is Administrator by default But this may have been changed when building Scarab The initial password is 1 This should have been changed after building Scarab This native Administrator account has all necessary permissions to manage yout installation of Scarab Note that most permission for a role are stored for every module separately If you add a new module you have to edit user s permissions for this new module Because of this there is no real administrator account which have all rights all over Scarab Creating Users Goto the section for user s in navigation for administrators e Select screen for creating a new user in navigation Enter all user data for the new user No field should be left blank e Save your sattings and the new user will be created Edit Users e Goto the section for user s in navigation for administrators e Select screen for managing users in navigation Select a user you want to edit and press button for edit user or if you want to
24. e 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 sys tem 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 informa tion
25. g the report Click on the Reports link This will take you to the Saved reports list page You can select a previ ously 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 several steps At first you have to select the issue types 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 link for the List Editor This will take you to the Cross module issue type list page You can use this page to define a list of issues types with in the current module or across multiple modules to be included in your report It is necessary that the is sue 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 e Select a previously saved cross module list to use e 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 e Add issue types to your report by checking the chec
26. kbox next to any issue type in the top section of the page and clicking the Add selected button e When you have selected the desired group of issue types for your report you can save the list for fu ture 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 22 Using Scarab report builder 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
27. lect where in the application you would like to go next Each op tion submits the issue and takes you to one of the following functional areas Assign issue e View this issue e Start page Return to home 16 Chapter 5 Searching for issues queries Query functionality includes defining a very specific query using a customized query using saved quer ies and accessing specific issue IDs You can also use the Issue List to access the last query e Know issue number enter it in Issue ID field e Know attribute values for issue use advanced query e Know approximate information about issue use custom query e 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 ac cess saved queries The Query bar The query bar provides quick access to frequently used search functionality e 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 e Advanced query allows you to specify detailed search criteria e 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
28. 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 permis sions 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 33 Workflow 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 i
29. m many other pages you can reach the module administration func tions but you may need to double click in the left margin to make the menu appear From there choose Global Data 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 attrib utes 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 mod ule not shared between them The module parent will also appear in the modules lists For instance the Source module which has Pac man 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 A
30. n one section This indicates that if you change the attribute clicking the button will change the options available to that attribute e Checkboxes Are used to select list items for modification In many cases helpful information is included directly on the screens to clarify unusual operations Er ror messages are provided in line to help identify where the error occurred and specific means for rem edy 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 Of 14 Scarab ergonomy ten you will find textual guidelines within the entry forms to help you through the form entry process Buttons Tabs Navigational buttons are available on each screen These buttons perform actions on the data entered in the form The e Cancel cancels the process in which you currently are engaged Continue button will take you to the next part of the entry process e Done button will save your work and return you to the last process in
31. nd easily access informa tion 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 par ticular 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 data base 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 facil itate 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 10 Part Il Scarab for everyone
32. ntended 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 con dition 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 e Requireness of an attribute globally or module scoped e 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 condi tion Clicking Done you will be back on the previous screen and will be able to read the defined con dition 34 Chapter 11 Display an informational message This allows the administrator to display an informational message to all users connected or about to connect For instance to plan a maintenance operation Access this function using the Set default informational message link The entered message now appears on top of every page including the home page to all users Note The informational message is not persistent it is reset if you restart the web application 35 Part IV Advanced topics Table
33. of Contents 12 XML ImporUExport 2 eee tes meme TREE e IEEE Y EErEE 38 Introduction te ret egre 38 XME exportof ISSUES Oe Tet is e EIE Qr doar 38 XML export of metadata issue types attributes esee 38 XMLE IDOL et an n ee er erp dye ete Dese S det pene Ue ee DERE PAESE 38 13 Integrating Scarab and other tools eme 39 Integrating Scarab in Eclipse stidne ea REE He 39 Integrating Scarab in Netbeans sees 39 Integrating Scarab and Maven Maven 1 39 Connecting your Maven project and Scarab 39 Linking the Changes plugin and Scarab sese 39 Integrating Scarab in TWiki ence Hehe 40 37 Chapter 12 XML Import Export Introduction Scarab allows module administrators to export e issues of a module data issue types and attributes of a module metadata import e 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 Access the XML import export functions using the Administration menu XML export of issues Select XML export in the Current module section Note In the default Role configuration you just need the Observer role in a module to have access to
34. ports 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 or ganize 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 23 Using Scarab report builder In the Report builder click on either the Row content tab or the Column content tab Select the content type for this heading in the Select content type drop down box Select the options you wish to include in the first heading of your report Click the Update button 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 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 Select the options you wish to include in this heading When finished click the Update button 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 ne
35. s 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 15 Chapter 4 Entering and managing issues 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 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 suppor
36. sions 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 se lected 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 but ton 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 21 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 in clude a single or multiple issue types in a single or multiple modules To access Scarab reports Select module in which you want to start definin
37. 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 e Search by attribute e Searching by personnel e 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 by attribute The first 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 values are 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 re quirements 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 data base errors If jdoe needs to refine the search criteria fur
38. stone 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 up wards 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
39. t or other type conversations to be viewable and editable by any parties interested in the pro gress of an issue Save frequently entered information The issue entry template feature allows you to create a fre quently 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 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 re maining 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 at tachments see Attachments Before submitting your issue you can se
40. te Pret 14 Navigation Dar ette eese iet themed ethan CERE OE EE e 14 Entry forms ie ore o E E ve eee fel ob weve eted 14 hun rr 15 m 15 Results and selection pages tree ee tette ao Pere IR EET Rene 15 15 Customizing the user interface iseia roi eones rs kosb herr rhe E rete rra 15 4 Entering and managing issues eee enm eme emere 16 Entering an 158 Pe RETE Re 16 5 Searching for 165068 qUerIeS ic eere nt ches Or ENDE e ER LEER NEEESE 17 The Query UEM 17 Issue ID cce estie t e ete See tosta 17 Advanced queries 18 Search by attribute eeepc ne Ced te oen ce optet ete tee eod eoe eee Seo peti 18 Searching by personnel n ee emen 18 Searching by state change ettet Ree Rr rens 18 eism 19 S ved queries eire RP og pe UR erp nisseasy xr S 19 How to an illustrated five minute tutorial on using and defining simple queries 20 Cross module queries eter e I ROTER ye 21 6 Using Scarab report builder Heer 22 Selecting 3ssue types ms esci oeste e Ege tepore gie Gedy 22 Row and column con
41. tent I He E eher 23 Datatypes oe SE ee PA es 23 Sorting attribute options and user attributes into headings and groups 23 Selecting users and attributes 20 0 0 eee cece cece ee ee e 24 Reporting dates i iei oet t cse eret 25 Generating and saving reports 2 0 0 0 cece eee eee 25 III Scarab for module administrators emen 26 7 Creating and managing modules Hee 28 Creating a new module etri ether E Qaeda seb RETE pees 28 Editing a module erre epe mre Rer EET E ERR 28 8 Manage users and permissions in Scarab sssssssee eeea een eeueeegs 29 Administrator rite eei ete 29 Creating ERG en A RN o Ee Ue Ee 29 Edit Users ions cette toe re e rete o oh Eee itp e eave sh Ie odee te Fo Dine 29 Scarab User s Guide Creating Roles eti RE Wm eque OU NP ERIS 29 Managing User Roles ecce emet et d EET ote ie tis 30 9 Best Practices coo oe ER No etude e NR edu epus 31 Prototype cn eeepc ort etes tese Stace o o onte ci ot tore e ox Pee vue Perte ds 31 Sharing a module with a customer sese 31 USE CaS EE 31 A possible solution en eke cobb eeepc eere ER EE pE eiee 31 Workflow isst rm p rer He EERE Rr NEEE teret eth PEPIPp OP RES 33 Introduction x aeree e rior yess ap Tre diei en t 33 Basic Workflow
42. ther other attributes can be defined When de fining 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 Depend ing on what user attributes have been defined you can search by the commitor and or the assignee 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 18 Searching for issues queries time When the view preference is based on Issue state or status the sort order is not necessarily alpha betical 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
43. this functionality XML export of metadata issue types attrib utes This section to be written XML import Select XML import in the Current module section Note In the default Role configuration you just need the Observer role in a module to have access to this functionality 38 Chapter 13 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 ex ample Eclipse RSS Reader http morphine sourceforge net presence projects rss index html 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 quer ies Say you want to keep an eye on the history of the PACSI 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 A NetBeans plugin allows to include Scarab issues in the to do list
44. 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 e 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 of ten MySQL but other databases such as Oracle and PostgreSQL are supported How does Scarab differ from other issue tracking sys tems 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
45. tqk 0 tem plate RSSDataEx port vm feedType QueryFeed queryId 10000 userId 1l type rss 2 0 refresh 1 header Stitle Sdescription format St Slink Stitle 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 As signedTo 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 re fresh time to only one minute 41
46. w you have reached the grid The grid is a very nice feature in the new Queries UI Here you have all issue types defined for this module as columns and values of one attribute as rows plus a total row Every cell in the table is a count that tells you how many issues have this attribute value in the different issue types The example displayed here is rather trivial You have only one issue its issue type is De fect and the functional area is none of UserInterface Setup or Help the Functional Area is un defined for this issue All cells are navigable if you click the number 1 in the Grand Total cell AII issue types total you get the list of all issues in this module OK there is only one Let s say you want to browse all issues that are new In the view by attribute drop down list choose Status Now the grid has changed and you get the issue count by Status You may click the 1 designed by the red arrow to display all New Defects To define a query that will list all issues in the module check and click Define query to list all Defects you could have checked the corresponding issue type instead Since you want to list all issues you should not define any selection criterion Click Save this query You are almost done Just give this query a name required an optional description and if you want others to use this query you should define the availability as module you probably need to
47. which you were engaged e 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 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 result
48. ws 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 ac cess 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 e 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 ascend ing 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 i
49. xt to the heading and click ing the Edit selected heading button You can delete previously defined heading by clicking on the ra dio 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 On the Row content tab or the Column content tab select a heading containing the Attribute op tion s content type and click the Edit selected heading button 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 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 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
Download Pdf Manuals
Related Search