View Only

How to Decide: Which Jama Reporting Tool To Use

By Shawnna Williams posted 03-25-2020 10:11


Jama Reporting Tools

Jama comes with several tools to export your data: 

  1. Word and Excel Exports and Office Templates
  2. Velocity Reporting 
  3. BIRT Reporting 

Lets take a closer look at our Word and Excel Exports and Mail Merge-based Office Templates options. These tools are great for quickly getting information out of Jama Software simply but sometimes the built-in Word and Excel Exports and Office Templates don’t quite give you what you want without post-processing. Exports and Office Templates can export your data into a formatted “document” (with headers, footers, a table of contents, cover page and heading levels). That said, they are limited when you need to customize the following: 

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. 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. 

Sourced from Community article: Introduction to Advanced Reporting  

Alright, so what if you find that you do need to add some logic, custom formatting, grouping of like items, and/or access to child items? You know that you have special considerations that require more control over the report output than Word templates are able to provideNote: if you can use the simpler option, we highly recommend it! 

Custom reporting will be the best way to get your data the way you want itLuckily, Jama also includes the ability to upload reports created using Velocity and BIRT. But now we are faced with this next question: which tool should you use? 

To help in this decision, take a quick look at this chart showing comparison across Velocity, BIRT and Office Templates (also available on page 4 in Advanced Custom Report How To Guide).  

Jama Reporting Tools Comparison Chart 



Office Templates 

Output to Word 




Output to Word using Word's Styles 




Output to Excel 




Output to HTML 




Output to PDF 




Possible to run report based on data results viewed in Jama (current view) 




Ability to generate charts and graphs 




Apply programmatic logic and use parameters 




Ability to re-import in Jama and update existing items 




Access to Jama's API 




Ability to run SQL queries for data 




Embed images into document 





When considering Velocity Advanced Reporting: 

Velocity is a Java-based language that comes with the web server Jama is installed with. It calls the Jama Velocity API (not the Jama REST API) and exports the data as HTML. 

When to Use Velocity for Your Report 

  • When your final report needs to be a “document” (export with headers, footers, heading levels, Table of Contents, etc.)
  • Relationships  – usually with logic applied to them 
    • Example: Only show Subsystem Requirements downstream from this System Requirement 
  • You need to show more than one item type in a single table
    • Example: One row shows the Requirement fields as well as its Verification status
  • When logic has to be applied to the data in the report
    • Example: Only show items with a certain Status 
    • Example: If a Test Case Status is Passed, make that cell or text green. If it has Failed, make the cell or text red
  • Context-based reports – The user pre-selects the data to send to the report from a Component, Set, Folder, Filter, Baseline, etc
    • This makes the report very flexible

What Skills Do You Need to Create Custom Velocity Reports?  

  • You are comfortable writing software scripts 
    • You will have to navigate a template-tag systemintegrated directly into Jama Software’s internal Velocity API, to integrate through sets of items then evaluate each item to define how it will be handled.  
  • You prefer a simple, text-based interface 
    • No special software to download, the Velocity tags are in the HTML
    • You can do your editing in whichever Text Editor you choose
    • Syntax similar to other embeddable scripting languages so, this method would work best with users who have experience writing scripts (as per above)
    • You’d like to run your report on user-specified sets of items 
      • You have the option to run Velocity reports as “context-sensitive” and can run these reports against only the item or group of items the user is viewing when the report is generated
        • Opens up the functionality of running reports 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 
      • Velocity allows you specify multiple control flows using conditional statements and loops

    Community Velocity Reports 

    Community reports are reports that are free for customers but are as-is -- they can be found in our GitHub Community Reports repository.

    Customers can download the report(s) and install them on their own Self-Hosted instance or request that a report is uploaded to their Cloud instance by contacting Customer Care.

    • Upstream Traceability 
    • Test Results Report – Grouped by Test Case 
    • Test Results Report – Grouped by Test Cycle 
    • Review Center Stats Report 
    • Sync Status Report

    When Considering BIRT Reporting

    BIRT is a freeware tool with a WYSIWYG interface, allowing you to directly query the Jama database using SQL queries. 

    When to Use BIRT for Your Report

    • The report will be displaying charts and graphs 

    • Dashboards/Analysis (sometimes)
      • If the analysis requires the report to get more than one level of relationships, Velocity would be a better choice

    • If there aren’t appropriate API calls (Velocity API)
      • Example: The report needs to show comments from a review
      • Example: The report shows how many people logged on to Jama in a given day 
    • Rollup/grouping tables (sometimes) 

    What Skills Do You Need to Create Custom BIRT Reports  

    • You are comfortable writing SQL queries 
    • Be familiar with Jama Software’s database schema 

    • Fluent in SQL to know how to select statement to join multiple tables while filtering out the data you need 
    • You prefer a GUI interface 
    • You will need to install and learn the capabilities of the separate BIRT editor -- this will require the dedicated time of an independent learning personality
    • You’d like your report to contain visual representations of data
    • BIRT’s editor is great for visual learners; allowing you to build your report by adding and arranging components on a page, built-in tools render charts, graphs and tables with ease

    Community BIRT Report

    Community reports are reports that are free for customers but are as-is and can be found in our  GitHub Community Reports repository.

    Customers can download the report(s) and install them on their own Self-Hosted instance or request that a report is uploaded to their Cloud instance by contacting Customer Care.  

    • Review Center Comments Report 
    • Visual Utilization Report 
    • Utilization by Project 


    Developing Your Own Custom Reports

    Self-Hosted Customers: Customers using Self-Hosted instances of Jama can develop their own reports and upload to their sites as needed.  

    Cloud Customers: If your instance is Cloud by Jama, you will need to purchase a Self-Hosted sandbox for development. Once your report is ready to move into production, Jama’s Customer Care team can upload it for you. 

    Instructional videos can be found here on our Education page under Advanced Reporting, and Jama Consulting Services can also be engaged for training that is tailored to specific reports. 

    Contact your Account Manager if you would like more information on training or a Self-Hosted sandbox. 

    Jama Report Development

    If your team does not have the resources or the time to develop your own report, Jama Consulting Services can develop the report for you. Contact your Account Manager for more information about these services. 

    1 comment


    05-04-2020 09:17

    Creating word with BIRT might be a brave attempt for large documents.