Debugging velocity scripts

If you are reading this you will probably be aware of how velocity can be used to spice up applications. Here's a quick summary:

• Velocity can be used to render dynamic html pages based on data stored by your application.
• Velocity can make your application more clever by using it to calculate field values, lookup lists and user permissions, or perform specific actions, execute triggers and validations.

This document describes how to investigate possible mistakes in velocity scripts. Solving a problem in your blueprint is described in the document Solving a blueprint problem.

Syntax and semantics

A mistake in any piece of velocity script (or in any programming code), is either a syntax mistake, meaning you have made an error in the "grammar" of the script language, or a semantic mistake, meaning there is something wrong in the logic of your script. A syntax mistake requires a different debug strategy than a semantic mistake. We'll describe both of these below.

To be more specific, not every error is strictly a syntax or a semantic error. It could also be that database has incorrect data and your script has difficulty in dealing with this, or perhaps a file could not be found. Or your script might not have anything to do with the error if the application engine itself has a bug.

Debugging velocity for dynamic html pages

In this case a mistake in velocity is quite easily spotted. A syntax mistake will be returned immediately to the screen, always in the top right corner. You will also see anything the engine was able to render up until the occurrence of the mistake. This depends on the nature of the mistake.

Example of a velocity error message

Debugging velocity when used in your blueprint

To get a picture of the state of the context you are writing velocity in, it is possible to get a table of contents holding all the current variables and their values. This is done by printing the variable $toc, in an environment with a screen output, like so:

$toc

When no variables have been declared by hand, the table of contents in the $toc variable looks something like this:

Testing your Velocity

When making a Velocity script on the development environment, it may be necessary to use constant values to test it. For example a script that uses the user record of the current user may set it to a constant value when there is no user record, as follows:

 #if(!$session.getUserRecord())
   #set( $userRecord = $session.getRecord('person', 6))
#end

This speeds up testing, but introduces some security risks. If this file is brought to the production environment as is, this script may inadvertently provide access to the user record of a real person.

Another way of speeding up testing is by supplying a test id through the request. Again, when a file using this technique is brought over to production, a security breach is created. This file now provides a way of accessing every record of a class through use of request parameters.

To mitigate these risks, it is strongly advised to write tests in a seperate Velocity file, that is recognizable by name as a test file. This way, the odds of accidentally bringing over potentially risky tests to the production environment are minimized.

Read more about these risks on this page.