Velocity Reporting update FAQ (updates start with Jama Connect 8.42)

By Kristina King posted 09-13-2019 11:32


What are these changes?

The Velocity engine is being updated, requiring new template syntax for customers' reports.

Why is Jama Software making these changes?

Updating the Velocity reporting process to the new format will improve the overall quality of these reports in several ways:

  • Improving overall security
  • Increasing the stability of reports over time
  • Simplifying the Report building process 

How does this impact Jama Connect users at my company?

Jama Connect users are not expected to be impacted immediately, but with any change in tooling, there is a risk of fringe issues not being immediately visible due to the highly customizable nature of the application.

All custom Velocity report templates will need to be modified to a slightly new format in order to ensure full functionality is retained. The Jama Software development team has created a conversion script that will perform the heavy burden for self-hosted customers. Likewise, this same script will be performed server side on our cloud to help ease the change.

Cloud: At the time of 8.44 release, Clients who have not contacted the Support team to change Velocity early will be updated automatically and revised reports will be available to your teams automatically.

Self-hosted: We created an analysis script for internal use on the reports you sent us. We identified templates and functions which are no longer supported with the updated engine and found replacements where possible. A conversion script will also be available for assisting in converting your Velocity report templates. This will assist in narrowing the scope of work needed by your teams to transition. Here is a link to the GitHub repository for the conversion script: Velocity Report Updater.

These customers are encouraged to send copies of Velocity report templates to Jama Software for review so that template functions with less frequent usage can be reviewed for a potential fix in the 8.48 Spring Standard release. 

When can I start using the new feature?

All customers can use it as soon as the 8.42 release is deployed or installed.

Can I choose not to opt in?

Temporarily, yes. This is opt-in for the roll out phase, but this is a short window and delaying may impact your teams later. 

Cloud: Prior versions of Velocity will be disabled upon deployment of the 8.44 release, but previously created reports will be converted to the new syntax automatically. 

Self-hosted: Prior versions of the Velocity template syntax will be disabled upon upgrade to the Standard 8.48 release. Failing to upgrade will result in installations that do not have access to the new security and performance improvements this update provides.  Only the new Velocity template syntax will be supported with the 8.48 release.

Where can I see the documentation?

You can see all of the Velocity documentation via this link. Make sure to refresh your page, because if you've visited before, the older data may be cached.

What elements have been changed and how?

We've created data sources that group the methods used in reports into related domains. Replace any references to items in the left column with the data source in the right column. This is best for informational purposes, our recommendation is to use the linked conversion script (Velocity Report Updater) to avoid manually making these changes to your reports.



11-16-2021 05:43

@Bridget Dowling, the name of the interface is spelled with a capital "D", but the object itself is writte non-capitalized:
So your approach is correct and expected.​

11-16-2021 05:36

Can you confirm if I should use $DocumentSource or $documentSource. I was using $DocumentSource  but I couldnt get $DocumentSource.getAllVersionsByDocumentId($ working until I changed $DocumentSource to $documentSource. Can you please clarify. Thanks

04-15-2020 11:32

Hi @Mike Mattinson, I have been told that the OrganizationDao is no longer available to use, but there is an Organization object that is returned by other objects. For example, if you get a Project, you can call getOrganization on that project and get the Organization object.​ Hope this helps.

04-14-2020 02:34

Where is OrganizationDAO? I am looking at it in the  and don't see it anywhere in the update script??

11-11-2019 01:53

there has been a feature-request regarding disabling of macro-caching. Has this been considered in the course of the engine changes?
BTW: We have started looking into the effort that it will take us to translate the reports from old to new velocity. The updater seems to do a good job. Except for the $velocityReportUtil.getValueForField() we did not need to manually rewrite anything yet.


10-22-2019 07:19

Hi @Jan Hoevelmann,

Please go ahead and reach out to Jama support to request this activation, as support's assistance is advised.

Thank you,

10-21-2019 02:15

The corresponding release notes state that:
"The changes to Velocity are currently released as opt-in and must be turned on by a system administrator for Jama Connect on-premises instances."

I did not find an option in the system properties (root login) or anywhere else that allows to activate this opt-in. Did i miss this crucial information in the release notes or the reporting update FAQ?