Why should I use an advanced reporting tool instead of Word exports?
Word exports are a wonderful tool for getting information out of Jama Software quickly and simply, and if you don't have exacting requirements for what your report will look like we heartily recommend using that first! However, many users have special considerations that require more control over the report output than Word templates are able to provide. A few of the more common use cases for moving beyond Word templates are as follows:
- Ordering of documents
Word templates will always order the included items in the same order that they appeared in Jama Software when the export was generated. If you’d like to make sure like items stay together or certain item types always display before others, you’ll need to use a custom export.
- Style formatting
Though we have support for basic text formatting like bullets and text decoration, Word templates do not support control for page formatting options like section breaks or custom page numbering. Though neither BIRT nor Velocity provide analogues for every option available to native Word documents, they’ll provide a broader level of control than Word exports do.
- Ancestors and descendants
Word templates have limited support for children, but BIRT and Velocity both allow much more access to follow relationships and tree structure through multiple levels.
- Conditional logic
BIRT and Velocity both allow much more control over when and where to display information than Word does. If you’d like to display an item’s status, but only if it was created more than 30 days ago and has an upstream relationship to a Feature, you’ll need to use an advanced reporting engine.
Which advanced reporting tool should I use?
Both BIRT and Velocity are powerful reporting engines and a proficient user can use either one to create almost any report they’d like. However, the tools and methods for building these reports are very different, and depending on your needs and your previous experience you’ll likely find that you prefer one tool to the other. To get a feel for the strengths of each tool, it may be helpful to compare the preconfigured reports that come standard with Jama Software. The Test Plan Summary report (available in the top-level Reports menu) is a good example of BIRT’s capabilities, and the All Item Details report (from the Exports > Office Templates menu item) shows what Velocity is suited to.
Please note that both BIRT and Velocity output their results in HTML; those results can be saved into a Word file, and styled with Office XML, but neither will provide access to all of the functions and options of a native Word document.
Use BIRT if:
- You are comfortable writing SQL queries
BIRT’s method of getting information to feed into the report requires you to write SQL queries that return discrete sets of data. To do anything more than display a simple list of objects, you’ll likely need to be familiar with Jama Software's database schema and fluent enough in SQL select statements to join multiple tables and filter out the data you need.
- You prefer a GUI interface
- You’d like your report to contain visual representations of data
BIRT’s editor allows you to build your report visually, by adding and arranging components on a page. In addition, it contains built-in tools to easily render charts, graphs and tables.
Use Velocity if:
- You are comfortable writing software scripts
- You prefer a simple, text-based interface
Velocity tags are nested into HTML, which makes for an extremely simple interface and no necessary special software; you’ll do your editing in whichever text editor you prefer. This approach means you won’t have access to tools like visual layout views or results previews, but it is extremely lightweight, portable, and easy to jump into. Since the syntax is similar to other embeddable scripting languages, Velocity will likely look familiar to many users with experience writing scripts.
- You’d like to run your report on user-specified sets of items
Like our Word templates, Velocity reports have the option to run as “context-sensitive,” meaning they will be run against only the item or group of items the user is viewing when the report is generated. This makes Velocity ideal for reports you'd like to run against a wide range of projects, item types and other variables.
- You’d like your report to iterate over sets of items and apply conditional logic
Though both BIRT and Velocity can perform data transformation reasonably well, Velocity will allow you to specify multiple control flows using programming concepts like conditional statements and loops.
We have created some step-by-step guides for Velocity: Writing a Velocity report step by step (read this first) and Writing a context-sensitive Velocity Report.