Knowledge Base

Information is up-to-date.
Please note that Jama versions prior to 8.42 will require an old version of Velocity, which uses different syntax.

Note that user-created Velocity reports can be uploaded to Self-Hosted versions of Jama only. Cloud customers should contact their account owner for more information about writing reports. 

It is possible to generate context-sensitive reports using Velocity. This guide demonstrates starting with a basic template and building the report through multiple iterations, making small changes at each step so that it is easy to see what worked and what did not. 
 
Context-sensitive reports are similar to a regular report in Jama, except that information about the user’s current view is passed to the report automatically. Context-sensitive reports are run from Export > Office Templates instead of from the Reports menu.
 
The report in this example shows the number of comments for each item in the current view. To run any of the examples, save the example code in a text file named "CommentsPerDocument.vm." In Jama, Select Admin > Reports and add a report with the following settings:

To run the report, navigate to a Project and Set of Items, then select Export > Office Templates > Comments Per Document.
 
Step 1: Report Template

Velocity reports are fundamentally just HTML markup, so start with a very basic layout.  

  
    Comments per Document
  
  
  Comments per Document
  

 

 

Step 2: Project Information and Date

Add information on the project being viewed using the $project variable provided automatically by Jama. Use DateTool to show the date and time when the report is run.

Note: if there are items from multiple projects in the report (for example, when reporting on search results), only a single project will show up in the $project variable.

  
    Comments per Document
  
  
  Comments per Document
  Project: $project.name

  $dateTool

  $project.description

  

 

Step 3: List Documents

Get a list of documents in the current view from the $documentList variable and show them in the report. 

  
    Comments per Document
  
  
  Comments per Document
  Project: $project.name

  $dateTool

  $project.description

  #foreach( $vDoc in $documentList )    
    $vDoc.document.documentKey - $vDoc.document.name - $vDoc.document.lastActivityDate

  #end
  

 

 
Step 4: Change Date Formats

Use dateTool to give dates a more readable format. For more information on available dateTool formats, check out the How-to Velocity Dates with dateTool article.

  
    Comments per Document
  
  
  Comments per Document
  Project: $project.name

  $dateTool.long

  $project.description

  #foreach( $vDoc in $documentList )    
    $vDoc.document.documentKey - $vDoc.document.name - $dateTool.format('short', $vDoc.document.lastActivityDate)

  #end

 

 
Step 5: Add Number of Comments for Each Document

Use the CommentSource.getCommentCount method to get the number of comments for each document.

Background information: The getCommentCount method uses ScopeId and RefId as parameters. ScopeId is used to indicate what type of object the comment belongs to (Document, Review, Baseline, etc.) and RefId is the API ID of that particular object. 

    Comments per Document
  
  
  Comments per Document
  Project: $project.name

  $dateTool.long

  $project.description

  #foreach( $vDoc in $documentList )
    ## 5 is the scopeId for documents. 
    #set($commentCount = $commentSource.getCommentCount(5, $vDoc.document.id))
    $vDoc.document.documentKey - $vDoc.document.name - $dateTool.format('short', $vDoc.document.lastActivityDate)

    Comments: $commentCount

  #end
  

 

 
Step 6: Add Formatting

Format the results in a table, and use CSS to set the font and table formatting.

   Comments per Document
    
      body { font-family: sans-serif;}
      h1 { font-size: 1.5em; text-align:right;}
      table { border: 1px solid #EEE; }
    
  
  
  Comments per Document
Project: $project.name

  $dateTool.long

$project.description 

  #foreach($vDoc in $documentList)
    ## 5 is the scopeId for documents. 
    #set($commentCount = $commentDao.getCommentCount(5, $vDoc.document.id))
    $vDoc.document.documentKey - $vDoc.document.name - $dateTool.format('short', $vDoc.document.lastActivityDate)

Comments: $commentCount

  #end