Knowledge Base

 View Only

Writing a Context-Sensitive Velocity Report Step-By-Step

By Jason Short posted 03-02-2016 17:37

  

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

#velocity#tutorial#bestpractices
6 comments
645 views

Comments

10-14-2016 13:18

Hey Otmar! Thanks for checking out Jason's how-to. You made a good point about context-sensitive and how this article assumes you're familiar with it. I just updated Jason's article to link to another post explaining it, so thanks for saying something about it!

10-14-2016 07:24

Hi Jason!

This step-by-step into is very, very useful.Thank you a lot for this.
One thing: I did not recognized the term "Context Sensitive" in your description - this creates a lot of emtpy reports :D (now I can smile about that).

Thx again!

Best regards from Europe/Austria,
Otmar

-i

03-07-2016 19:29

Hahahaha. I can let you know that we're working on putting you out of business right now. ;) 

03-07-2016 14:55

I am the only person that I know at my company hacking Shawnna's fantastic Velocity report. People ask me for upstream and downstream items. People also ask me to expose or hide fields. I feel very much needed and loved :-) Frankly, if Coverage Explorer can be enhanced to show upstream items, then I'll be out-of-business, which is a good thing. Please put me out of Velocity templates hacking business :-)

03-03-2016 16:17

How is the Velocity reporting going for you, Swoo? I remember you tweaking one of the traceability reports a while back. 

03-03-2016 14:23

Jason, thanks for sharing. Personally I think Velocity is very powerful but relatively difficult to learn and edit. I just copy and paste an existing template from Shawnna :-) The only hint I like to give is to encourage people to use an editor that slightly shows the syntax. Here is a link. http://wiki.apache.org/velocity/VelocityEditors I happen to use TextPad with a very simple Velocity syntax. Have a good day. swoo