JSONTool - Documentation topics on: apis,json,jsonobjects,remote,viewtool,webservices,.


The JSONTool allows you to call local or remote json-based RESTful web services and parse the results for inclusion in a velocity template, page or widget. The following examples show how to use the JSONTool and JSONObjects with JSON in dotCMS.


By default, the JSONTool is mapped in the Velocity Context with the variable name $json:

  • $json == com.dotmarketing.viewtools.JSONTool

The following methods are supported:

fetch$json.fetch( URL, Timeout )Retrieve and parse JSON.
generate$json.generate( Object )Generate JSON objects from Java objects, strings, or maps

Retrieving and Parsing External JSON ($json.fetch)

The $json.fetch() method retrieves and parses JSON. The method returns a JSON object whose properties can be traversed via the . (dot) operator.


$json.fetch( URL, Timeout )
URLSpecifies the URL of the JSON resource to retrieve.
To retrieve JSON from a file, upload a file into dotCMS and specify the dotCMS URL of the uploaded file (referenced from the root of the dotCMS Site Browser tree).
TimeoutTimeout in milliseconds.


  • The timeout is specified in milliseconds (not seconds).
  • The timeout value is optional.
    • If no timeout value is specified, the default timeout is used.
    • The default value may be changed by modifying the URL_CONNECTION_TIMEOUT property in the dotmarketing-config.properties file.
      • Important: It is strongly recommended that all changes to the dotmarketing-config.properties file be made through a properties extension file.
  • The timeout specifies the total time to wait to both make the connection perform the read, and the Import Tool will automatically kill the connection after the specified time, regardless of what state the import is in.
    • Therefore the timeout should be greater than the time it takes for both the connection and read of the JSON resource.


The following example fetches a JSON object from an external site and displays different properties of the object.

#set($myjson = $json.fetch("http://www.omdbapi.com/?t=Battlestar%20Galactica&y=&plot=short&r=json"))

<p>The title is: $myjson.Title</p>
<p>The year is: $myjson.Year</p>
<p>The rating is: $myjson.Rated</p>

The results of the code above are:

The title is: Battlestar Galactica
The year is: 2004–2009
The rating is: TV-14

Parsing Arrays and Loops

If the JSON property is an array, you can loop over the array using Velocity's #foreach directive:

#set($myjson = $json.fetch("http://imdbapi.poromenos.org/json/?name=battlestar%"))

#foreach($show in $myjson.shows)
    <p>$show.name ($show.year)</p>

The code above lists every version of the Battlestar Galactica television show, including the year it was broadcast.

Limiting JSON Results

To limit the number of results returned in the JSON query, use Velocity $foreach.count and #break directives to exit the #foreach loop as soon as the count is met. The following example limits the previous code to only display 3 results:

#set($myjson = $json.fetch("http://imdbapi.poromenos.org/json/?name=battlestar%"))

#foreach($show in $myjson.shows)
   #if( $foreach.count > 3 )
   <p>$show.name ($show.year)</p>

Handling Alternate JSON Array Formats

The JSONTool handles JSON arrays in certain specific formats automatically; however JSON arrays can be formatted in different ways, and for some JSON array formats, additional processing may be required to be able to iterate through the array results. If you can not iterate over a JSON array using the standard loop syntax (above), you must first read the JSON array and create a JSON object from it, and then iterate over the JSON object, as in the following example:

#set($jsonData = $import.read("http://imdbapi.poromenos.org/json/?name=battlestar%"))
#set($jsonData = "{data:${jsonData}}")
#set($jsonObject = $json.generate($jsonData))
#foreach($show in $jsonObject.data)
   <p>$show.name ($show.year)</p>

Creating JSON Objects ($json.generate)

The $json.generate() method generates JSONObjects from Java Objects,Strings or Maps. The JSON object values can be populated with static or dynamic content from your dotCMS instance.


$json.generate( Object )


The following code generates a JSONObject from a java.collections.Map, demonstrating how to serve a JSON object from your site.

#set($mymap = $contents.getEmptyMap())
#set($dummy = $mymap.put("one","value 1"))
#set($dummy = $mymap.put("two","value 2"))
#set($dummy = $mymap.put("three","value 3"))
#set($myjson = $json.generate($mymap))


<p>The value of key "one" is: $myjson."one"</p>

The code generates the following results:

{"two":"value 2","one":"value 1","three":"value 3"}
The value of key "one" is: value 1

Parse Internal JSON Files

The following example code will allow you to parse JSON files that are stored on the dotCMS file system. Since the #include directive is only aware of files on the system and not files in dotCMS's virtual file system, use $webapi.getAssetPath to convert the virtual path to the system path, and then $json.generate to convert the file contents into a variable.

#define($file)#include($webapi.getAssetPath("/your/dotCMS/file/path/data.json", $host.identifier))#end
#set($data = $json.generate($file.toString()))  

-Thanks to Leonardo Bell for providing this example :-)