Writing a context sensitive Velocity report step by step

Note that user-created Velocity reports can be uploaded to on-premises versions of Jama only. Hosted 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 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 and 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. More information on available formats available can be found in this 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
Add the commentDao object and use the getCommentCount method to get the number of comments for each document.

#set($commentDao = $applicationContext.getBean("commentDao"))

  
    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 = $commentDao.getCommentCount(5, $vDoc.document.id))
    ${vDoc.document.documentKey} - ${vDoc.document.name} - $dateTool.format('short', $vDoc.document.lastActivityDate)

    Comments: ${commentCount}

  #end
  

 


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. 
 
 
Step 6 – Add formatting
Format the results in a table and use CSS to set the font and table formatting.

#set($commentDao = $applicationContext.getBean("commentDao"))

  
    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))
    
      
      
      
      
    
  #end
  DocumentKeyNameLast Activity Date# of Comments${vDoc.document.documentKey}${vDoc.document.name}$dateTool.format('short', $vDoc.document.lastActivityDate)${commentCount}