Writing a context sensitive Velocity report step by step

By Jason posted 03-02-2016 20:37

  

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}
 


#velocity
#tutorial
#bestpractices
6 comments
474 views

Comments

10-14-2016 16: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 10: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 22:29

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

03-07-2016 17: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 19: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 17: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