Quick Guide to Navigating the Velocity API Documentation

By Shawnna Williams posted 06-30-2021 10:26


When creating a Velocity report, you will need to call the Jama Velocity API but, at first glance, it can be overwhelming. This short guide is intended to give some clarity to navigating the documentation.

When visiting the API home page, select the version of Jama the report will be running against (the links in this article will be to the most recent self-hosted version).

The Getting Started section gives you a quick look at a few of the tools you can use in your report (and you can find more details about how to code in Velocity here).

Commonly used examples in the generic Velocity tools and libraries include:
  • Turn a value into an integer: $mathTool.toInteger( $
  • Format a date: $dateTool.format( "MM/dd/yyyy", $doc.createdDate)
  • Sort a list: #foreach( $s in $sortTool.sort( $docList, "createdDate: asc"))
  • Get a custom field: #set( $rationale= $velocityReportUtil.getValueForField($doc, "rationale", $dateFormat ) )
Most data can be extracted from the API using a Source. These Sources allow you to get specific objects from a given section of Jama. DocumentSource is used often because it gives access to Jama items. Other frequently used Sources are ReviewSource, BaselineSource, and TestSource. 

Clicking on the Source's name will display the Source's methods.

Source Methods
When the Source is clicked on, all of its Methods are displayed in the right column with the Object types to be returned listed on the left. For example, to get the downstream relationships for a document, the report might need DocumentSource's getRelationshipsForDocument:
The text at the left shows the type of object that is returned (DocumentDocument in this example). Clicking on the object link will show the returned object's methods:

Don't forget about the inherited methods at the bottom.

Commonly Used Objects
  • Document (DocumentSource)
  • ContourItem (DocumentSource)
  • DocumentDocument (this is a Relationship) (DocumentSource)
  • DocumentNode (DocumentSource)
  • Project (ProjectSource)
  • User (UserSource)
  • TestCycle (TestSource)
  • TestRun (TestSource)