Knowledge Base

 View Only

BIRT and Velocity Custom Reports Created by Our Services Team Available for Your Jama Instances (Community Reports)

By Kristina King posted 04-01-2015 18:30


Information updated January 2022

In partnership with Jama's Consulting team, we'd like to offer some custom reports, including usage reports, for our customers. These reports were written with either BIRT or Velocity so, if you are a self-hosted customer and have experience with the appropriate platform, you can manipulate them to suit your needs.

Please note that these reports come as-is. Customer Care limits the support of these reports to uploading to Jamacloud.
Self-Hosted Customers of Jama: There will be no harm done if you would like to install a report and try it out. If you have root or admin access to your instance, you can install the report. Make sure to configure the parameters as displayed in the image found in the report's folder. Some reports have multiple versions which cater to different databases, so pay close attention that you download the correct one.
Cloud Customers of Jama: You will need to submit a request for us to upload one of these offered reports as-is for you. To do this, please send an email to indicating which report you would like to use and the URL of your instance -- this will create a ticket with Customer Care, who will confirm when the report is uploaded. If you would like to have us customize one of these templates, it would be considered a Services Engagement.

If you are interested in having a consultant tailor a report for you, build one from scratch, or train you on how to write your own, please reach out to your Jama Account Manager to scope out a project. Cloud customers can upload any Word templates shared there, while Self-Hosted customers can use any file they see fit on their instance. Cloud customers can also request that we upload a Velocity or BIRT report you have built yourself, as long as it was created on a self-hosted sandbox.

Available Reports Can Be Downloaded from Our GitHub Repository.

Note that context-sensitive reports will be appear in Export > Office Templates, whereas non-context-sensitive reports will appear in the Reports link at the top of Jama Connect.

Velocity Reports

Compatible with Jama versions running on Java 7 or 8 -- should work with most versions of Jama

  • The Test Plan Report provides test plan coverage complete with description, creation dates, creator name and steps.                                

  • The Upstream Traceability Report provides for the export of upstream traceability coverage as an alternative to Trace View.
    • Note that there are two versions of this report:
      • The original Upstream Trace shows six (6) upstream levels of relationships, but is only compatible with versions of Jama Connect released prior to 2020 (due to changes to the Velocity engine)
      • Upstream Trace Two Levels version shows only two (2) levels. We recommend the use of this report if you have a large number of items and find the original report takes too long to render

  • The Sync Status Report shows all items in any project that are synced with the selected items, along with their Sync Status, and can be run in HTML or Excel. One thing to note: this report displays all items that share the same Global ID with each selected item. If items are reused often, the report may take a long time to run. If this is the case, users may want to select smaller sets of items from which to run this report.

  • The Excel Export Report, which was created to help mitigate the effects of defect SOS-BUG-854 -- this defect caused Excel reports with multiple or large pick lists to take an exceptionally long time to generate. The Excel Export Report is intended as a replacement for the stock exporting options when pick lists are needed. Note that this exports plain text only; formatting will be stripped. This defect was fixed in 2015.2.

BIRT Reports

  • Supported in 2015.1+; Java 8 required
    • *Why is Java 8 required? The BIRT engine upgrade in Jama 2015.1 is compatible with Java 7, but the reports updated for, or created with, the BIRT update not compatible with Java 7.
      • There is a version unique to each supported database type, so make sure you download the correct version.

  • The Review Center Comments Report will export current revision comments on open reviews. In order to run the report in a given project, the user must be assigned to one or more reviews in that project as either a Reviewer, a Moderator, or an Approver. What this means is that, when we load the list of reviews for the report parameter list, we load them based on the project you're in and the user you're logged in as. As a result, public reviews won't show unless a user is a Reviewer, a Moderator, or an Approver, even though they can look at the review itself.

  • The Utilization by Project Report displays the number of specific Jama objects (users, comments, reviews, etc.) used by a project over a selected date range. 

  • The Visual Utilization Report visually displays Jama Utilization data over a specified amount of time. 

  • The Login Data Report is a non-context-sensitive report that builds a single-sheet Excel file of user login data over the past ninety (90) days. The report gathers information such as the login attempt status, the login attempts username, the license type of said user, the login and logoff time in UTC time, and the logged-in session duration. The time duration of how far the report will check can be modified by adjusting the hours values on line 421.

  • The Login Report (8.x) is a graphical report that shows how many people were logged in during a given hour. It also contains a table below the graph with every login -- this way, the report user can export the data to Excel and manipulate it. Note that you can see how many people are logged in during a particular hour, but you don't know how many have logged out*. So, to find how many users you have in Jama at a given time, you will have to assume that you could have as many as the previous hour's logins plus the current hour's logins for a total BUT you might also have as few as the current hour's logins. It's really just an estimate.

*This is because the database can only track when users use the Log Out link; if their session doesn't end through clicking on that link, this isn't tracked.


  • The Usage Report (8.x) shows a list of all users for any given date range, and shows how many days they have logged in -- a day would be at least one login on that date; if they logged in more than once that day, the day would still only be counted once -- and also shows the date of their last login. Note that each user is listed once for each group they are in so, if you are in an Admin group and in the Project Managers group, you will be listed twice.

*This report does not work in Jama 8.36+ (will work up until that version.)  

  • The Baseline Diff One Column Report (8.65+) is a visually-enhanced version of the Baseline Comparison Report, and used to measure progress in your requirements from baseline to baseline, similar to a Jama Connect version comparison view.

If you're using 2015.1+  with Java 8, make sure you update your reports to run on the new BIRT engine.

If you are unable to download a needed report because your IT policies block GitHub, please submit a support ticket and we will provide you with the report. Indicate a) which report you would like b) Jama version you are running and c) the database you're utilizing.

#velocity #BIRT


02-25-2022 01:07

I've tried the Review center stats report and have found a problem. Items of type runs is not listed in the "Items in the review" list. 

I can't find out how we can generate a report that shows that a run is approved.

12-10-2020 15:17

Hi, I downloaded and generated the Upstream Trace Two Levels report.  Upon opening, Excel shows a warning "The file format and extension of xxx don't match.  The file could be corrupted or unsafe..." when I open the .xls file.

I guess that because the file is HTLM, not excel format...but is this an expected behavior?

10-13-2016 02:31

I got it to work now. I made a mistake in the installation. I did not see the "Criteria" section.

10-12-2016 14:35

Thanks, Vegard. That should all check out (provided the Java 1.8 is Oracle's JDK and not OpenJDK). Do you know if anyone has edited the Review Center Comments report on your end? It's worth trying a reinstallation of the report; I checked old tickets and didn't see any common issue with the RC Comments Report for 2015.5. 

One thing to consider is the role of the user who is trying to export these reports. In order to run the report in a given project, the user must be assigned to one or more reviews in that project as either a reviewer, moderator, or approver. What this means is that when we load the list of reviews for the report parameter list, we load them based on the project your in, and the user you're logged in as (so public reviews won't show unless a user is a reviewer, moderator or approver, even though they can look at the review itself). Have you had multiple people attempt to run this report?

10-12-2016 04:11

MySQL 5.5.52

tomcat 7.0.56

java version "1.8.0_101"

Java(TM) SE Runtime Environment (build 1.8.0_101-b13)

Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)

10-11-2016 14:11

We tested these reports locally with 2015.5, but since they aren't a support part of the product they don't get thorough testing. I haven't heard there is a universal issue with 2015.5 and this report, though.

What database are you running Jama on? What version of Tomcat & Java is installed on the Jama server?

10-10-2016 08:25

Hi, I am trying to use the Review Center Comments Report, but get the same errors as Steve explained above "a report can be produced, but only for one Review, regardless of which is selected.  That was my experience anyway, and the report produced each time was for a Review that had been closed and archived.  "

The reason for Steve's problem seemed to be compatibility to 2014.2, hence I assume that it is the same problem that I experience. I currently run 2015.5, but are planning to update to Jama 8 soon. Does this reports run on 2015.5/Jama 8 or is it planned to update the report? If not, have anyone made any variants to the reports to run on newer versions?

06-28-2016 12:42

The only content that changed is where the reports can be downloaded from (GitHub instead of Box). I also recently updated the article to include screenshots of the reports.

06-28-2016 12:32

Kristina, I was just reading this thread after being forwarded a recent email from you about the GITHUB.  It would be tremendously helpful if there was some way to identify what changed in the post since the original publication.  Updating a year old post with new information and not being able to figure out what information is old and what information is new, is not a good user experience. 

06-22-2016 15:27

Yup! Thanks!!

06-22-2016 15:04

Kevin, yesterday we finished setting up a Github repo for these reports, but I haven't had a chance to update this post yet. Are you able to access that?

06-22-2016 14:11

Ditto. (IT blocks Can you please share all the Velocity reports via a ticket?

Thank you!

12-01-2015 15:26

Hey Jennifer! At this point, no, because the bugs in question were fixed for 2015.2, so we won't be putting in additional report development time.

11-24-2015 16:42

Is there any way to get the Jama Excel Export to create with the steps on a different line for each, like how the "regular" pokey Excel Export does? We are currently stuck with being unable to run the Export because of lag, but the Jama one (on the same exact set/context) puts all of the steps into one cell.


11-23-2015 16:30

Kristina - could you have the 2015.1 version for Excel Export   and Utilization by Project sent to me? Thanks!

11-06-2015 14:28

FYI to anyone who has downloaded and installed the Excel Export; our reports guru Shawnna just updated it to be be context sensitive (previously it included all fields, not just what was visible), and it's faster to boot.

10-30-2015 17:37

Sure thing, Gus! You should see that here in a few minutes. 

Thanks for the feedback about Ask Jama. I'm really happy to hear that you have found value in it—that's exactly what we were hoping for. We don't want to invite you to Ask Jama sessions to meet any sort of Marketing numbers, but to share actual helpful processes and tips. I'm glad you showed up :)

10-30-2015 16:47

Kristina, could you please forward the Upstream Traceability report and the Sync Status Report? Our security settings don't allow the download.

BTW, the Rolling Review seminar was extremely informative. We've been running Jama reviews for years and had not thought to use them this way. Jama is a powerful tool and it's very beneficial to learn how others are using (like that seminar and this post). Thank you.

10-23-2015 17:29

Yes, that is correct—that box is how it knows that it's geared towards a specific view you're in rather than "hey, pull the specific fields/data in the report". 

I don't have any other ideas. I'll look at tickets and see if any issues have been reported. (Although that's tough, since it's not something really support!)

10-23-2015 16:36

Correct -- is that right?

I actually recall that before I checked the box, I did see the report in the list, but it returned empty results. This made me go back and look at the instructions / screen shot, which indicated the box had to be checked.

10-23-2015 15:24

I imagine you've checked the "Context Sensitive" box?

10-23-2015 13:09

Regarding the Upstream Traceability report -- I've uploaded it to both a 2014.2 server and a 2015.1 server, and ensured that "Visible to Users" is set to "true", but in neither server does the report show up as an option in the Run Reports list when I have a set of items in context.

Am I missing something obvious?

07-29-2015 23:00

Hi Kristina,

Never mind. I answered my own question when I discovered that Shawnna's code included an example. So I edited my questions. You can still give Shawnna a pat on the back :-)

Hi Kristina,

I like the upstream report very much!  Thanks to Jama and @Shawnna publishing it.

In my case I need to expose a few built-in and also custom fields. So I've customized a version of the report. I consulted this post about how to expose custom fields in Velocity. I need a tip from you or the queen of reporting @Shawnna to tell me how to expose custom fields in the 1st level. Assuming "domain" is a custom field.

For the base level, I know this works

<td>$velocityReportUtil.getValueForField($vDoc.document,$vDoc.documentTypeDto, "domain", $dateFormat,true)</td>

For the first level, I know this works for a built-in field

The answer:



06-19-2015 19:29

Hi Steve,

Full disclosure, when I grow up I want to be a BIRT and Velocity report writer :-). There are some very talented people on this forum who are familiar with BIRT and Velocity. I believe Jama also provides fee-based report consulting services. I want to learn BIRT because I can use a graphical development and debug environment, but I need to learn SQL--my brain is not wired for all those join statements yet :-) Velocity seems like a very powerful reporting engine, but I cannot get over the fact that I have to use Notepad/Textpad to edit Velocity control codes, HTML codes, Jama API. At the company we also have other semi proprietary reporting solutions because Jama nicely provide API's to access the data. --- I have never met @Shawnna before in person or on-line--be ready to butter her up.. :-)

06-19-2015 19:19

Thanks for the help SWOO ...did I pronounce that right ;-) 

I'll definitely 'attempt' a dive into all this.  I may need to commandeer one of these software developers hiding out around here ...if I can figure a way to pry those headphones off long enough to sneak a request in!

06-19-2015 18:59

Hi Steve,

As regard to your questions about custom reports, you might take a peek at a User Guide. For example, here is the on-premise version: 

Please go to the section on BIRT and Velocity. 

Here is an official posting:

Here is an interesting thread:

06-19-2015 17:59

Thanks Kristina.  I can confirm that the 2014.1 version is not useful for 2014.2, or at least not useful more than once.  By that I mean that a report can be produced, but only for one Review, regardless of which is selected.  That was my experience anyway, and the report produced each time was for a Review that had been closed and archived.  

Does Jama offer any online tutorials, webinars, reference material for creating custom reports such as this, or can you point me to other resources?  We will absolutely need the ability to output data in a form usable / reviewable by others who don't have access to Jama.  I realize that the best approach here is probably to install the latest Jama release but apparently we're hardware constrained at present, and I suspect we'll always need a report slightly different, with just a little bit more, than what's readily available - that just seems to be our norm!

06-19-2015 17:31

After all that pinning down of version availability, I am here to confirm you're right, Steve. It is so: there is no Review Center Comments report for 2014.2. It is possible that the version from 2014.1 might work, but there is no guarantee on that. There was never a QA effort prioritized to check the compatibility with 2014.2—once we decided to put these reports in the Community, we had a release date for 2015.1.

06-19-2015 16:15

Just heard about the Review Center Comments report on the Q&A webinar today.  Very excited to hear it existed.  Then learned that it was only available for version 2015.1 and I thought great, we're running version 2015.2, but then learned it works only on Java v8, but we can only support Java v7 currently, so how are we running Jama 2015.2?  Then learned there's a bug in Jama and we're really running Jama 2014.2, but then learned there were reports available for earlier Jama versions, and now see a version for 2014.1 but not for version 2014.2!  Say it isn't so, say it isn't so!  Is there not a RC Comments report available for version 2014.2 or v4.5.3 or build date 2014/11/20 17:24   ...I think that may be as specific as I can get re: our version.

05-29-2015 14:40

Note that we now have a Review Center Comments report available for hosted customers. (Yay!)

04-08-2015 16:05

Pradeep, this appears to be an error caused by the "base status" field that is being called. The report was written with the default Status field in mind, so if you are using a custom Status field, it would need to be called in a different way. However, because these reports are offered as-is, we won't be able to provide any more support on this error.

04-07-2015 19:16

Felix, I opened a Support ticket and attached the report folder for you. Just make sure you grab the pertinent report :)

04-07-2015 15:56

I've noticed status doesn't get resolved if it's an item type that can't have (upstream) relationships, such as folders. What item types are you seeing this on?

04-07-2015 12:58

For some reason. My report does not resolve Base Status or any separation.. Any idea why?
$docDao.getDocument($h2) etc.

04-07-2015 06:26

I've the same problem with
Could you please send the report to me?

04-06-2015 19:14

You are correct—the report should display all items that you have displayed in your view while you export.

04-06-2015 19:03

Hi Kristina,

Thanks for sharing this wonderful report.
I am struggling in trying to trace only a subset of requirements with this upstream traceability and it looks that this is not the case here. This report displays traces of all the requirements/item types of the view I am generating this report from. Is this right? 


04-02-2015 15:31

Looks like it is blocked. Please send it to me via email.

04-02-2015 14:39

Pradeep, I'll open a ticket with support to send the report to you that way. Does your IT department have blocked?

04-02-2015 12:33

Where do I download this (The Upstream Traceability report) from. The page is not loading for me. Can you please send it to me