# How to update deprecated Velocity code

> Replacements for the reflection-based patterns that no longer work, mapped to their modern Velocity Tool equivalents.

URL: https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/update-deprecated-velocity-code.html
category: Developing in Cascade
article-type: reference
content-kind: faq
release-availability: all
tags: velocity, upgrades
updated: 2026-10-06

Older Velocity code often reached into Java classes directly through reflection. Those patterns are deprecated, and each has a Velocity Tool replacement. This article pairs the old form with the new one.

## FieldTool.in for entity types

The `$_FieldTool.in(String)` method was used to reference entity types for the Locator Tool. New [Locator Tool](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#LocatorTool) methods locate each asset type directly.

Old:

```velocity
$_.locate($currentPagePath, $_FieldTool.in("com.hannonhill.cascade.model.dom.identifier.EntityTypes").TYPE_PAGE, $currentPageSiteName)
$_.locate("path/to/format", $_FieldTool.in("com.hannonhill.cascade.model.dom.identifier.EntityTypes").TYPE_FORMAT, $currentPageSiteName)
$endCal.add($_FieldTool.in("java.util.Calendar").YEAR, $numberOfYearsToDisplay)
```

New:

```velocity
$currentPage
$_.locateFormat("path/to/format")
$endCal.add($_FieldTool.in($endCal).YEAR, $numberOfYearsToDisplay)
```

## Generating random content

`java.util.UUID`, `DigestUtils`, and `java.util.Random` were used to generate random strings and UUIDs, commonly for unique DOM element ids. Use [generateUUID()](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#_StringTool_generateUUID) and [random()](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#_MathTool_random) instead.

Old:

```velocity
#set($id = "video-${class.forName('java.util.UUID').randomUUID().toString()}")
$class.forName('java.util.Random').newInstance().nextInt(9999999)
```

New:

```velocity
<div id="video-${_StringTool.generateUUID()}">
$_MathTool.random(0, 9999999)
```

## Unescaping content

`StringEscapeUtils` was used to unescape previously escaped content. The [Escape Tool](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#_EscapeTool_unescapeHtml) now covers this.

Old:

```velocity
$class.forName('org.apache.commons.lang.StringEscapeUtils').unescapeHtml("&lt;br/&gt;")
```

New:

```velocity
$_EscapeTool.unescapeHtml("&lt;br/&gt;")
```

## Regular expressions

`java.util.regex.Pattern` was used to compile regular expressions. Use the [Regex Tool](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#RegexTool).

Old:

```velocity
#set($_pattern = $class.forName("java.util.regex.Pattern"))
#set($_ids = $_pattern.compile("#([\w_-]+)").matcher($_s))
```

New:

```velocity
#set($_ids = $_RegexTool.compile("#([\w_-]+)").matcher($_s))
```

## Concatenating with StringBuilder

`java.lang.StringBuilder` was used to concatenate strings without introducing whitespace. A [String Tool method](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#_StringTool_getStringBuilder) now provides an instance.

Old:

```velocity
#set($sb = $class.forName('java.lang.StringBuilder').newInstance())
#set($sb = $sb.append('foo'))
${sb}
```

New:

```velocity
#set($sb = $_StringTool.getStringBuilder())
#set($sb = $sb.append('foo'))
${sb}
```

## Checking an asset's type

`getClass()` combined with `getSimpleName()` was used to check an API object's type. Use `getAssetType()`.

Old:

```velocity
#set ($chosenAsset = $currentPage.getStructuredDataNode("assetchooser").asset)
#if ($chosenAsset.class.simpleName == "PageAPIAdapter")
...
#end
```

New:

```velocity
#set ($chosenAsset = $currentPage.getStructuredDataNode("assetchooser").asset)
#if ($chosenAsset.assetType == "page")
...
#end
```

## Checking a data structure's type

The [Property Tool](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#PropertyTool) gained `isString`, `isMap`, `isList`, `isSet`, and `isIterable`.

Old:

```velocity
#set($map = {})
#if ($map.class.simpleName.contains("Map"))
...
#end
```

New:

```velocity
#set($map = {})
#if ($_PropertyTool.isMap($map))
...
#end
```

## Checking whether an object is numeric

Old:

```velocity
#set($number = 3)
#if ($number.class.forName('java.lang.Number'))
...
#end
```

New, using the [Number Tool](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#NumberTool):

```velocity
#set($number = 3)
#if ($_NumberTool.isNumeric($number))
...
#end
```

## Converting a map to a JSON string

[$_SerializerTool.toJson](https://www.hannonhill.com/cascadecms/latest/articles/developing-in-cascade/script-formats/velocity-tools.html#_SerializerTool_toJson) outputs a Map as JSON directly.

Old:

```velocity
#set($map = {"test": "testing", "array": [1, 2, 3]})
#foreach ($key in $map.keys)
  #set ($value = $map.get($key))
  ...
#end
```

New:

```velocity
#set($map = {"test": "testing", "array": [1, 2, 3]})
$_SerializerTool.toJson($map)
```