Request, Response and Session

Last Updated: Mar 4, 2022
documentation for the dotCMS Content Management System

dotCMS automatically maps the users request, session and the server's response to object for use in all Velocity contexts, including templates, pages, vtls, content, widgets, etc.

Request ($request)

The visitor's request object (HttpServletRequest) is available in all Velocity contexts. You can access the request by referencing the $request object in your Velocity code.

The following are several commonly used Request object methods:

Method ExampleDescription
$request.getHeader("user-agent")Retrieves the visitor's browser user agent.
$request.getAttribute( "javax.servlet.forward.request_uri")Get the request URL for a URL mapped page or a page redirected to from a Vanity URL.
$request.getAttribute( "")Get the content object of a URL mapped piece of content.
$request.getParameter("id")Retrieves the parameter of the GET/POST variable id.
Note: Make sure to escape this method call if you use it on a page, to avoid XSS security issues: id: "$UtilMethods.xmlEscape( $!request.getParameter("id"))"
For more information on using URL parameters in your pages and Velocity code, please see the URL Parameters documentation.
$request.getRemoteAddr()Retrieves the visitor's public IP address.
$request.getRequestURI()Retrieves the base URL used to access a page.
Can be used to construct parameter URLs for the current page.
$request.getSession().setAttribute( 'com.dotmarketing.htmlpage.language', '2')Sets a new language (Ex: language_id=2), in the current session.

For a complete list of methods available, please see the Java documentation for HttpServletRequest.

Accessing dotCMS User Agents

In addition to common User Agents, dotCMS also sets a request attribute when dotCMS tools are rendering pages. This allows you to specify custom behaviour when those tools are accessing and reading your pages. For example, when the Site Search is reading all your HTML Pages you may want to “hide” the footer of your HTML Pages from the index process to ensure only relevant information is indexed.

Note: These values are set in a request attribute named User-Agent, not in the User-Agent header.

The User-Agent request attribute is set to the following values by dotCMS depending on the internal dotCMS tool accessing your content:

User AgentSet to this Value When
DOTCMS-CMISThe content is accessed from a CMIS client.
DOTCMS-HTMLPAGEDIFFThe content is queried and read in Preview Mode.
DOTCMS-PUSHPUBLISHThe content is being Push Published to a Static Endpoint.
DOTCMS-SITESEARCHSite Search is querying and reading your page.
DOTCMS-TIMEMACHINETime Machine is querying and reading your page.


#if ($request.getAttribute("User-Agent") == "DOTCMS-SITESEARCH") 
    ##Custom code... 

Response ($response)

The server's response (HttpServletResponse) is also available in all contexts. The methods available from the $response object include the following:

Method ExampleDescription
$response.sendError(404)Generates a 404 error (“Page Not Found”).
$response.addHeader("Powered-by", "dotCMS")Adds a Powered-by header to the response.
$response.setContentType("text/xml")Sets the content mime type to text/xml.

Note: Once output from the server has started, you will not be able to redirect or modify many attributes of the response mid-stream (such as content-type, error code, and redirect); any attempt to do so will fail, and will generate an error in your logs.

You may also use the $response object to perform redirects; please see the Redirects documentation for details.

For a complete list of methods available to you, please see the Java documentation for HttpServletResponse.

Session ($session)

You can access the user's session (HTTPSession) via the $session object. The user's session can be used to store state and values that can be retrieved across pages.

Note: This viewtool cannot be used to set session variables directly from a static page — e.g., one served via CDN — but can still be utilized via the Scripting API in such a case.

Several of the most commonly used methods in the session are displayed below:

Method ExampleDescription
$session.setAttribute("name", "Joe User")Assigns the value the value Joe User to the session attribute name.
Note: The name attribute is created if it doesn't already exist.
$session.getAttribute("name")Returns the value of the name attribute
(e.g., Joe User if used with the above example).
$session.removeAttribute("name")Removes the name attribute from the session.
$session.invalidate()Destroys the user's session.
Note: A new one will automatically be created on the next request.
$session.getAttribute( "com.dotmarketing.htmlpage.language")Get the language currently selected by the visitor.

Note: In high volume systems, it is generally bad practice to store large amounts of data in a user's session, as it can fill up the server's memory.

For a complete list of methods available to you, please see the Java documentation for HTTPSession.

Session Lifespan

By default, the system invalidates a session after 30 minutes of inactivity. This limit can be adjusted through $session.setMaxInactiveInterval(maxIntervalInSeconds). Once a session is invalidated, no method of the $session object suffices to reinstate it; a browser refresh or similar becomes necessary to generate a new session. However, using virtually any method of the $session object will suffice to reset the inactive interval.

A client-side script can interact with the $session object via the Scripting API to keep a session alive. For example:

setInterval(myTimer, 600000);

function myTimer() {

This activates the HTTP GET method of a custom keep-alive Scripting API once every 10 minutes. To create this example case, simply define a get.vtl file in /application/apivtl/keep-alive — or name it anything else you prefer. The contents of the VTL file can likewise be as simple as fetching a session's id, creationTime, lastAccessedTime, any attribute, etc. The data might be returned as follows:

$dotJSON.put("session-created", ${session.creationTime})

However, the Javascript example above isn't configured to receive a respons, and indeed the keep-alive doesn't need to return anything at all; it can consist entirely of the $session call.


On this page


We Dig Feedback

Selected excerpt: