Knowledge Base

Using Parameters in Velocity Reports

By Jason posted 02-08-2016 14:26

  
Please note that Jama versions prior to 8.42 will require an old version of Velocity which uses different syntax.


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($baseline = $baselineSource.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($document = $documentSource.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($release = $releaseSource.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($review = $reviewSource.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
9 comments
492 views

Permalink

Comments

Rob
03-18-2021 17:14

Hi, im trying to create an excel spreadsheet using velocity that shows all the requirements in $documentList,  However, I want to include a column next to each that shows the release date for the release that has been associated with each of the requirements in $documentList.  Any ideas on how to do this......please use small words as Im not really a developer.

Jason
06-09-2016 10: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

M
06-09-2016 06: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

Jason
06-08-2016 12: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)

M
06-08-2016 04: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

Jason
02-08-2016 20: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)

Rafael
02-08-2016 19: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.

Jason
02-08-2016 19: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>

Rafael
02-08-2016 15:26

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