URL Rewrite Rules

Last Updated: May 20, 2019
documentation for the dotCMS Content Management System

dotCMS ships with a Java implemention of mod_rewrite called tuckey. This allows you to set up rewrite rules which can both forward and redirect, using sophisticated rewrite rules and conditions.


The Vanity URLs feature provides almost all the functionality available via Tuckey, through a simple, codeless user interface which support Push Publishing and other rich dotCMS content features. It is recommended that you use Vanity URLs instead of Tuckey, unless you have a need for sophisticated rewrite rules or conditions which are not supported by Vanity URLs.

For more information on the different methods you can use to implement rewrites in dotCMS, please see the Redirects, Rewrites, and Forwards documentation.

Rule Types

You can create rules to either forward or redirect URLs.


Forwards rewrite the URL according to the rewrite rule, and change the URL displayed in the user's browser to display the new URL. For example, if you forward from the URL /en/about-us to /about-us?language-id=1, the URL displayed in the user's browser will change to display the rewritten URL (/about-us?language-id=1).


Requests URLs which match the “from” property will be HTTP redirected as specified in the rule. Redirects rewrite the URL according to the rewrite rule, but leave the URL displayed in the user's browser the same as it was typed in by the user. For example, if you redirect from the URL /en/about-us to /about-us?language-id=1, the URL displayed in the user's browser will remain as it was typed (/en/about-us), but the page displayed will be based on the rewritten URL (/about-us?language-id=1).

This allows you, for example, to create rewrite rules that add parameters to the end of the URL without displaying those parameters in the user's browser, or to create rules that allow the same folder on your site to be accessed with multiple different names.


  • Using Java code via an OSGI plugin.
    • This method is more technically demanding, but enables you to make changes dynamically, without the need to restart dotCMS.

OSGI Plugin

Rewrite rules may also be implemented via an OSGI plugin. The following example code implements a rewrite rule using a Java class. This Java class can be implemented and loaded dynamically as an OSGI plugin, without the need to restart dotCMS.


package com.dotmarketing.osgi.tuckey;

import org.osgi.framework.BundleContext;
import com.dotmarketing.osgi.GenericBundleActivator;
import com.dotcms.repackage.org.tuckey.web.filters.urlrewrite.NormalRule;
import com.dotcms.repackage.org.tuckey.web.filters.urlrewrite.SetAttribute;

public class Activator extends GenericBundleActivator {

    @SuppressWarnings ("unchecked")
    public void start ( BundleContext context ) throws Exception {

        initializeServices( context );

        // Create the rewrite rule with the specified request prefix "es"
        NormalRule esLangRewriteRule = new NormalRule();
        esLangRewriteRule.setFrom( "^/es/(.*)" );

        // Set the target page language ID request attribute
        SetAttribute langIdRequestAttribute = new SetAttribute();
        langIdRequestAttribute.setName( "com.dotmarketing.htmlpage.language" );
        langIdRequestAttribute.setValue( "2" );
        esLangRewriteRule.addSetAttribute( langIdRequestAttribute );

        // Set the target page language ID session attribute
        SetAttribute langIdSessionAttribute = new SetAttribute();
        langIdSessionAttribute.setType( "session" );
        langIdSessionAttribute.setName( "com.dotmarketing.htmlpage.language" );
        langIdSessionAttribute.setValue( "2" );
        esLangRewriteRule.addSetAttribute( langIdSessionAttribute );

        // Set the target page URL attribute
        SetAttribute cmsFilterUrlMapOverrideAttribute = new SetAttribute();
        cmsFilterUrlMapOverrideAttribute.setName( "CMS_FILTER_URLMAP_OVERRIDE" );
        cmsFilterUrlMapOverrideAttribute.setValue( "/$1" );
        esLangRewriteRule.addSetAttribute( cmsFilterUrlMapOverrideAttribute );

        addRewriteRule( esLangRewriteRule );


    public void stop ( BundleContext context ) throws Exception {
        unregisterServices( context );

For more information on creating and deploying OSGI Plugins, please see the OSGI / Dynamic Plugins documentation.


On this page


We Dig Feedback

Selected excerpt: