Redirects, Rewrites, and Forwards

Last Updated: Jul 29, 2022
documentation for the dotCMS Content Management System

There are several ways to perform URL redirects and rewrites in dotCMS. Some methods, such as Vanity URLs and Tuckey Rewrite Rules always perform the rewrite or redirect when a user accesses the forwarding URL, while other methods such as Velocity code and personalization Rules allow you to only perform the redirect or rewrite under certain conditions.

Redirect Types: Redirect and Forward

There are two basic ways to redirect a user to another URL: forwards and redirects (rewrites). A forward takes the visitor to the new URL without indicating to the browser or application that the URL has been redirected, and does not change the URL displayed in a visitor's browser. A redirect returns a code to the browser or application informing that the URL has been redirected, and replaces the URL in the visitor's browser with the new URL.

There are two different types of redirects, permanent (301) and temporary (302). Both behave similarly, except that search engines treat them differently, and using a 302 redirect may not pass the SEO benefits (e.g. page rank and link equity) to the new URL.

The following table summarizes the different redirect types:

StatusTypeVisitor's URLDescription
200ForwardUnchangedThe URL is forwarded to the new page without any notification to the browser, application or crawler that anything is out of the ordinary.
301Permanent RedirectRewritten
  • The application is redirected to the URL and notified that this is a permanent redirect.
  • Passes the SEO benefits of the original URL to the new URL.
302Temporary RedirectRewritten
  • The application is redirected to the URL and notified that this is a temporary redirect.
  • May not pass the SEO benefits of the original URL to the new URL.

Redirect Methods

dotCMS provides multiple different methods to perform forwards and redirects. The method you use determines:

  • What redirect types you can use,
  • Whether the redirect always happens or can be limited based on specific conditions (specified either via the user interface or code)
  • Whether the forwarding URL must be a fixed value or can be matched using a pattern.
  • Whether parameters can be used to extract some portion of the forwarding URL and include it in the redirected URL.

Note: The most common method for performing redirects is Vanity URLs. It is recommended that you use Vanity URLs for your redirects unless you have need of other features which are not available in the Vanity URLs feature.

The following table shows the different redirect methods available:

MethodSupported TypesTrigger on
URL MatchingParam Replacement
Vanity URLs200, 301, 302NoRegular expressionYes
Rules (Personalization)301YesExact matchNo
Tuckey Rewrite Rules200, 301, 302NoRegular expressionYes
Velocity: $response.sendRedirect()301YesExact match or URL Map patternYes
Velocity: Set Response Headers301, 302YesExact match or URL Map patternYes

Redirect Using Velocity Code

You can perform redirects with Velocity code by calling the $response.sendRedirect() method or setting the response headers.


Any time you use Velocity code to perform a redirect, you must follow the commands that perform the redirect with the Velocity #stop command. If you do not include the #stop, the redirect will fail with errors.

$response.sendRedirect() Method

In Velocity, you can perform redirects directly from a page or template using the $response.sendRedirect() method. For example, the following code will send a 302 (temporary) redirect to the visitor's browser when added to the top of pages or in your templates:


Setting Response Headers

To control the redirect status (301/302), you can set the response headers as in the following example:

$response.setHeader("Location", "$YOUR_NEW_URL")

Note: Since the above code sets HTTP Headers, it must be placed at the top of the page, before any HTML code which will be sent to the user's browser.

On this page


We Dig Feedback

Selected excerpt: