Knowledge Base

 View Only

Introduction to Advanced Reporting

By Alexander Kahn posted 03-11-2015 15:40


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 that 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 thirty (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 pre-configured 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, while 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
    BIRT is built on a combination of SQL, XML and Javascript, and it has its own dedicated GUI built on Eclipse to handle its complexities. It will require a bit of time to install and learn the capabilities of the editor but, once installed, this interface is extremely flexible and can make certain processes much easier than they would be otherwise.

  • 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
    Velocity uses a template-tag system that can iterate through sets of items, evaluate each item and define how it will be handled. These tags hook directly into Jama Software's internal API, which gives you access to safe, abstracted methods for gathering and relating information. This can be extremely useful if you plan on grouping objects, polling for related items, or checking complex sets of conditions. In form and function, this is very much like writing embedded Javascript in a webpage.

  • You Prefer a Simple, Text-Based Interface
    Velocity tags are nested into HTML, which makes for an extremely simple interface with no necessary special software required; you’ll do your editing using 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 who have prior experience with 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) that 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, and recommend checking them out!

#BIRT #velocity


12-21-2015 14:54

Thank you. I'm not certain how high or low the relationships need to be, but I appreciate the feedback. Determining whether BIRT or Velocity are the right solution is actually part of my mandate.

12-21-2015 13:29

Hi James-
Test Plans are actually documents, as would be your custom item called Test Case. 

Relationships are made by creating a record in the document_document table. If you are going to be reporting on relationships, I highly recommend creating your report in Velocity. The SQL queries needed to get relationships further than one level up or down would be too complex to make an efficient report. Relationships are very easy to report on using the RelationshipDao in Velocity.


12-21-2015 11:44

I am comfortable with writing SQL, and I'm fortunate enough to have a live-in Oracle Certified Professional to help (aka Darling Wife). What I'm not finding is enough information on the relationships in the Jama database  to write the queries I need (including in the SchemaSpy tool which Darling Wife seems to think is wonderful):

* How are documents attached to Test Plans? We have a custom item called a "Test Case" which I've been tasked to report out to replace current internal communications.
* How are relationships established between documents? We have a custom item called "Customer Requirement" which is supposed to be attached to the "Test Case" for contracts closure. I'm still trying to understand our internal usage for this relationship, which would seem to be done with Jama Relationship process.

I might be evaluating doing this same report with Velocity as I'm also a scripting fool... 

05-11-2015 14:09

Pradeep - I don't believe you can have a table of contents in HTML if you want page numbers. The only way you can have a TOC with page numbers is if it's ultimately exported into Word, because there are no page numbers in HTML. In HTML, I guess you could build one on the fly using a counter variable that gets incremented every time you spin through a header tag, but you would then have to spin through all of the items (or a good portion of them) once to get your TOC and then again to print the HTML.

05-08-2015 21:33

What is the best way to generate a table of contents for a velocity report? I tried inserting TOC in word and saved as html and then added HTML/VTL code to it. But TOC is not refreshing when exporting report in/as HTML. I don't want to go to word output as there are some other issues to deal with.