Using Parameters in Velocity Reports

By Jason posted 02-08-2016 17:26

  
Please note that with Jama 8.42 we have introduced an update to Velocity. These changes are optional until 8.44, after which the new syntax will be required. See the FAQ for more details on the update. This tutorial is still valid in terms of structure, but there are changes to the objects called. Generally speaking, we do not recommend copy-and-pasting code from these articles as it may change.


Report Parameters
(or Criteria) allow user-defined values to be passed into a report. An example scenario is to allow users to choose a specific Release or Test Plan to report on. Available parameter types can be found at http://help.jamasoftware.com/report_parameters.htm 
The parameters that will be passed to the report are defined when a report is created in Jama. http://help.jamasoftware.com/adding_custom_reports.htm
 
 
Examples of using parameters in Velocity code:
These examples demonstrate using each parameter type in a Velocity report. In each case, the parameter's Name is set to "myParametertype." For example, "myBaseline" or "myBoolean." (The name must be a valid Velocity variable name)
 

 
Baseline parameter:
Report Code:
Value from Jama: $myBaseline (Type: $myBaseline.getClass())<br>
#set($baselineDao = $applicationContext.getBean("baseLineDao"))
#set($baseline = $baselineDao.getBaseLine($mathTool.abs($myBaseline)))
Baseline object: $baseline.getName()<br> 
Result:
Value from Jama: 1 (Type: class java.lang.String)
Baseline object: B1 - 01/29/2016


 
Boolean parameter:
Report Code:
Value from Jama: $myBoolean (Type: $myBoolean.getClass())<br>
Boolean object: $myBoolean<br>
Result:
Value from Jama: true (Type: class java.lang.Boolean)
Boolean object: true
 

 
Date parameter:
Report Code:
Value from Jama: $myDate (Type: $myDate.getClass())<br>
#set ($secondsFromEpoch = $mathTool.abs($myDate))
#set ($dateObject = $dateTool.toDate($secondsFromEpoch))
Date object: $dateObject<br>
Result:
Value from Jama: 1454400000000 (Type: class java.lang.String)
Date object: Tue Feb 02 00:00:00 PST 2016
 

 
Location parameter:
Report Code:
Value from Jama: $myLocation (Type: $myLocation.getClass())<br>
#set($docDao = $applicationContext.getBean("documentDao"))
#set($document = $docDao.getDocument($mathTool.abs($myLocation)))
Document object: $document.getName()<br>
Result:
Value from Jama: 1758 (Type: class java.lang.String)
Document object: Business Requirements

 
 
Release parameter:
Report Code:
Value from Jama: $myRelease (Type: $myRelease.getClass())<br>
#set($releaseDao = $applicationContext.getBean("releaseDao"))
#set($release = $releaseDao.getRelease($mathTool.abs($myRelease)))
Release object: $release.getName()<br> 
Result:
Value from Jama: 37 (Type: class java.lang.String)
Release object: Spring 2016 release

 
 
Review parameter:
Report Code:
Value from Jama: $myReview (Type: $myReview.getClass())<br>
#set($reviewDao = $applicationContext.getBean("reviewDao"))
#set($review = $reviewDao.getReview($mathTool.abs($myReview)))
Review object: $review.getName()<br>
Result:
Value from Jama: 1 (Type: class java.lang.String)
Review object: Set: Business Requirements

 
 
String parameter:
Report Code:
Value from Jama: $myString (Type: $myString.getClass())<br>
String object: $myString<br>
Result:
Value from Jama: test (Type: class java.lang.String)
String object: test

 
 
Test Plan parameter:
Report Code:
Value from Jama: $myTestplan (Type: $myTestplan.getClass())<br>
#set($testPlanDao = $applicationContext.getBean("testPlanDao"))
#set($testPlan = $testPlanDao.getTestPlan($mathTool.abs($myTestplan)))
TestPlan object: $testPlan.getName()<br>
Result:
Value from Jama: 1850 (Type: class java.lang.String)
TestPlan object: Spring 2016 Test Plan
 

 
Questions and Answers
Q: Can I have more that one parameter of a given type?
A: Yes, just make sure the Name is different for each parameter.
 
Q: Do I have to name the variables "myVariablename"? 
A: No, though it is a good idea to have some kind of naming convention. The name must be a valid Velocity variable name

#tutorial #velocity
8 comments
383 views

Comments

06-09-2016 13:59

I think I see what's going on.

#foreach($n in $allnodes)
    #set($vdoc = $docDao.getDocument($mathTool.abs($n.id)))
    <h1>$vdoc.document.name</h1>
    <p class=MsoNormal>$vdoc.document.description</p>
#end

In your example, getting the nodes is working (the easy way to verify that is just to print out $n), but you're right - getDocument isn't returning anything.

That's because "$n.id" is the id of the documentNode, not the id of the document that node refers to. Also, $vdoc won't have a ".document." parameter (since getDocument is just putting the Document object straight in to $vdoc)

Try this instead:

#foreach($n in $allnodes)
    #set($vdoc = $docDao.getDocument($n.refId))
    <h1>$vdoc.name</h1>
    <p class=MsoNormal>$vdoc.description</p>
#end

06-09-2016 09:59

Thank you so much for your response . As suggested I have followed the below steps but I am unable to print the requirement description or name.

I have followed below steps to achieve the desired result.

1. To get the desired Location (Jama Parameter)

Value from Jama: $myLocation (Type: $myLocation.getClass())<br>
#set($document = $docDao.getDocument($mathTool.abs($myLocation)))
Document object: $document.getName()<br>
Document id : $document.id

2. To Get the documentNode for that document


#set($node = $documentNodeDao.getDocumentNode(5, $document.id ))

3. For that documentNode, to get all the children

#set($allnodes = $node.getAllChildNodes())

4. For each child DocumentNode, get the actual document it refers to ( May be this is where I am facing an issue where I am unable to get the actual document of the childnodes, hence I am getting $vdoc.document.name and $vdoc.document,description in the report)

#foreach($n in $allnodes)

#set($vdoc = $docDao.getDocument($mathTool.abs($n.id)))

<h1>$vdoc.document.name</h1>

<p class=MsoNormal>$vdoc.document.description</p>

#end

I tried multiple ways but was not able to get the desired information. Could you please help me with this.

Thanks,
Vijay

06-08-2016 15:44

The Location example above gives you the ID of a specific document (which ever one is picked in the Report screen).

To get the children of that document:
  • Get the documentNode for that document.
  • For that documentNode, get all the children
  • For each child DocumentNode, get the actual document it refers to
  • For that document, do whatever you want to do with the child documents. (Print name, description, etc)

06-08-2016 07:29

Hi All,


I am new to Jama velocity reporting. I am working on basic reports any help provided will be extremely useful.


when we build context sensitive reports, we use documentlist to run through the items available, but when we want to have global report using Jama paramters like ( Location,basleline date ,etc .,) the above code helps to get the desired location, but how do we iterate through those list of items available in that location.


for example, my location in the report points out to the 'requirements' in the project. I would like to get requirement name,description in that desired location.


Thanks,

Vijay

02-08-2016 23:01

I don't see a way to use the same trick with a Boolean parameter. From my testing Jama passes false if a boolean criteria is unchecked. (Rather than a null value)

02-08-2016 22:48

I agree that works reasonably well for most option types (though less clear for users), but what about for a boolean option? The option could be rephrased to make the default a clear state, but again that can get confusion for users and more error prone to maintain.

02-08-2016 22:21

There's not a way to set a criteria's default value inside Jama (I agree, that would be handy), but you can write the report so if the user doesn't select anything it will use a default value. For example:

Test Plan parameter:<br>  Value from Jama: $!myTestplan (Type: $!myTestplan.getClass())<br>
#if (!$myTestplan)
    ##No test plan selected, set default to 1850
    #set($myTestplan = "1850")
#end
#set($testPlanDao = $applicationContext.getBean("testPlanDao"))
#set($testPlan = $testPlanDao.getTestPlan($mathTool.abs($myTestplan)))
TestPlan object: $testPlan.getName()<br>

02-08-2016 18:26

Is there any way to set a default value for a parameter? this would be very useful