Documentation

Table of Content

 

Introduction

Thanks for choosing DNN Dynamic Redirect by weweave! DNN Dynamic Redirect offers you a highly flexible redirect solution for DNN. In contrast to other existing DNN redirect solutions, DNN Dynamic Redirect does not require adding modules to pages to implement redirects. Instead, it offers an admin user interface which allows you to easily manage your portal’s redirects.

If nothing else is stated, this documentation refers to the latest available version of DNN Dynamic Redirect.

 

Requirements

In order to use DNN Dynamic Redirect, make sure your environments meets the following requirements:

 

Installation

Please follow these steps to set up DNN Dynamic Redirect:

  1. Download DNN Dynamic Redirect from the download page.
  2. Log in to your DNN installation as host admin and select “Settings > Extensions” (DNN 9) or navigate to “Host > Extensions” (DNN 7 or 8).
  3. Select “Install Extension” (DNN 9) or “Install Extension Wizard” (DNN 7 or 8) and follow the process.
  4. After a successful installation you should see one new menu items: “Dynamic Redirect” under “Admin” where the portal-specific configuration can be performed.
  5. Navigate to “Admin > Dynamic Redirect”, select Host Settings and enter your license key in the popup.

 

Upgrading

Please follow these steps to upgrade your existing DNN Dynamic Redirect module installation:

  1. Download the latest version of DNN Dynamic Redirect for your DNN version from the download page.
  2. Make sure that your license key is still valid before performing the upgrade.
  3. Log in to your DNN installation and select “Settings > Extensions” (DNN 9) or go to “Host > Extensions” (DNN 7 or 8).
  4. Select “Install Extension” (DNN 9) or “Install Extension Wizard” (DNN 7 or 8) and follow the process.

 

Redirect Configuration

The actual redirect configuration of DNN Dynamic Redirect is performed portal-specific under “Admin > Dynamic Redirect”. When editing or adding a redirect, you can set the following properties:

  • Redirect Name: A unique name for your redirect
  • Description
  • Priority: If multiple patterns match, you can control the priority with which this rule is being considered for a redirect
  • Request type: Select “Page” if the redirect should only be performed if the user enters a URL to an existing page or “Any” if the redirect should be performed on any request
  • Requested URL: Requested URL (regular expression/regex)
  • Requested URL Format: Absolute, Relative, or RelativeDnnRoot (if your DNN portal is served from t a sub-directory, such as www.website.com/portal)
  • Requested URL Ignore Query: Perform case-insensitive query string matching
  • Requested URL Ignore Case: Perform case-insensitive URL matching
  • Force Login: Check if you want your visitor to be logged in before performing the redirect (if he/she isn’t already logged in)
  • Rule: If the redirect should only be performed on a specific condition, you can define a rule that defines the criteria using a XML syntax (see XML Rule Definition Syntax)
  • Enabled: Check if this redirect is active
  • Redirect URL: Absolute or relative target URL that is being redirected to

Redirect Import

Redirects can be easily imported from a CSV file. Under “Admin > Dynamic Redirect” select “Import redirects” and upload your CSV file in the import wizard. The CSV file has to meet the following requirements:

  • The first row is used to define the column order and has to contain all headlines (“Redirect name”, “Description”, “Priority”, “Request type”, “Requested URL”, “Requested URL Format”, “Requested URL ignore query”, “Requested URL ignore case”, “Force login”, “Rule”, “Enabled”, “Redirect URL”).
  • A comma is used as field separator.

Please note that the column “Redirect name” needs to be unique. If a redirect with the same “Redirect name” already exists, the import updates that existing redirect with the data from the import file instead of adding a new redirect.

A sample CSV file look like this:

Redirect name,Description,Priority,Request type,Requested URL,Requested URL Format,Requested URL ignore query,Requested URL ignore case,Force login,Rule,Enabled,Redirect URL
Redirect1,Redirect description 1...,1,Any,/facebook,Absolute,true,true,false,"",true,https://facebook.com
Redirect2,Redirect description 2...,2,Any,/google,Absolute,true,true,true,,true,https://facebook.com

XML Rule Definition Syntax

Dynamic Redirects are defined by a set of rules. These rules are expressed as XML. This section lists the available XML tags and gives some samples.

Logical Operators

Multiple rules can be combined by the logical operators AND and OR, and single rules can be negated by using the logical NOT operator.

The AND operator combines multiple rules by a logical AND. Thus, all rules enclosed in the AND tag must evaluate to true.

<and>
    <rule1 />
    <rule2 />
</and>

The OR operator combines multiple rules by a logical OR. Thus, at least one rule enclosed in the OR tag must evaluate to true.

<or>
    <rule1 />
    <rule2 />
</or>

The NOT operator negates a single rule enclosed in the OR tag. This, if the rule returns true, it is negated to false and vice versa.

<not>
    <rule1 />
</not>

Please note that every ruleset must be enclosed in a logical outer tag. Thus, every ruleset must start with and AND, OR, or NOT operator – even if there is only one rule in your ruleset.

The logical operators can be combined with each other by nesting the corresponding tags.

<and>
    <rule1 />
    <rule2 />
    <or>
        <rule3 />
        <rule4 />
        <not>
            <rule5 />
        </not>
    </or>
</and>

The pseudo-rules <true /> and <false /> can be used for testing purposes. They always evaluate to true or false.

Role Membership

Dynamic redirects can be built on static (so administered manually by a site operator) or dynamic roles (using DNN Dynamic Roles). Please note that this rule always evaluates to false for anonymous requests.

<and>
    <member role="goodCustomer" />
    <member role="originGermany" />
</and>

In this example, the user must be in both roles “goodCustomer” and “originGermany” in order for the ruleset to evaluate to true.

  • role (required): The role to be checked for.

Cookies

You can check if a certain cookie is present, and (optionally) if it has a certain value.

<cookie name="first-visit" pattern="^2014-.*$" />

In this example, the user must have a cookie with the name “first-visit” present and the cookies content has to start with the string “2014-“.

  • name (required): The name of the cookie.
  • pattern (optional): The value of the cookie to match. This is a regular expression. If this parameter is not specified, the existence of the cookie is sufficient for the rule to evaluate to true.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.

Referer

Check the referer/referrer. This is the url of the page the user visited before coming to your site. Please note that you cannot rely on the referer: In many cases, browsers do not set this http request header.

<referer pattern="^http(s)?://(www.)?weweave.net/.*$" />

In this example, the user must come from weweave.net – either via http or via https, and either with or without “www.”.

  • pattern (required): A regular expression to check the referer against (case insensitive).

Browser

Check the browser (interpreted user agent) a user uses. Please note that user agents can be faked, so you should not rely on the correctness.

<or>
    <browser type="internetexplorer" minVersion="6" maxVersion="9" />
    <browser type="firefox" maxVersion="20.1" />
</or>

In this example, the user must use Internet Explorer 6-9, or Firefox <= 20.1.

  • type (required): One of the following values: internetexplorer, firefox, chrome, opera, safari.
  • minVersion (optional): The minimum version (major and minor, inclusive).
  • maxVersion (optional): The maximum version (major and minor, inclusive).

User Agent

Check the raw user agent reported by the client. Please note that user agents can be faked, so you should not rely on the correctness.

<userAgent pattern=".*lynx.*" />

In this example, the user must use a version of Lynx.

  • pattern (required): A regular expression matched against the HTTP request header “User-Agent” (case insensitive).

Request Parameter

Check if a certain request parameter (GET or POST) is present and, if desired, it has a certain value.

<requestParam name="query" pattern="^error.*$" method="get" />

In this example, the HTTP GET parameter “query” must be present and its value must start with the string “error”.

  • name (required): The name of the request parameter.
  • pattern (optional): A regular expression of the required parameter value.
  • patternIgnoreCase (optional): Set to “false” to ignore case. Default is “true”.
  • method (optional): The request method employed. One of the following values: get, post. If this parameter is not supplied, the parameter is searched in both GET and POST section.

Date

Check if the current date is within a certain range. The server-side timestamp is used for this check.

<date min="2014-12-01" max="2014-12-24" />

In this example, the current date must be between 12/01/2014 and 12/24/2014.

  • min (required): The minimum date (inclusive). Format: yyyy-MM-dd
  • max (required): The maximum date (inclusive). Format: yyyy-MM-dd

Time

Check if the current time is within a certain range. The server-side timestamp is used for this check.

<time min="09:00:00" max="15:30:00" />

In this example, the current date must be between 9:00 AM and 3:30 PM.

  • min (required): The minimum time (inclusive) in 24h format. Format: HH:mm:ss
  • max (required): The maximum time (inclusive) in 24h format. Format: HH:mm:ss

Date and Time

Check if the current timestamp is within a certain range. The server-side timestamp is used for this check.

<dateTime min="2014-12-01 15:00:00" max="2014-12-31 09:00:00" />

In this example, the current date must be between 12/01/2014 3:30 PM and 12/31/2014 9:00 AM.

  • min (required): The minimum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss
  • max (required): The maximum timestamp (inclusive) in 24h format. Format: yyyy-MM-dd HH:mm:ss

SQL Query

Run an SQL Query and evaluate the result. The rule evaluates to true if the value of the first column in the first row is “1”, and to false otherwise.

<sql query="SELECT COUNT(*) FROM sales WHERE customer_id = @[email protected] LIMIT 1" />

In this example, there must be a row in the “sales” table where the customer’s ID matches the current user’s ID.

  • query (required): The query to execute. You can use the placeholder @[email protected] which will be replaced with the current user’s ID, and @[email protected] which will be replaced with the current portal’s ID. Please note @[email protected] is always null for anonymous requests. Both parameters are passed as int.

Geo Location

Check the user’s IP address against MaxMind‘s geo ip database. You need an account at MaxMind in order to use this rule.

<geoMaxMindCountry userId="1" licenseKey="abc" service="city" country="US" />

In this example, the user’s IP address must be located in the US.

  • userId (required): MaxMind User ID.
  • licenseKey (required): MaxMind License Key.
  • service (required): MaxMind’s endpoint to be used. One of the following values: city, country, insights
  • country (required): Two-letter ISO Country Code (i.e. “US” or “DE”).

Random

Evaluates randomly to true or false (i.e. useful for A/B testing).

<random ratio="0.5" />

In this example, the rule returns true in 50% of all requests, and false in the other 50%.

  • ratio (required): The ratio between 0.0 and 1.0 at which the rule evaluates to true.

Administrator User

Checks is the current user is an administrator.

<administratorUser />

Super User

Checks is the current user is a super user.

<superUser />

Unauthenticated User

Checks is the current user is an unauthenticated user.

<unauthenticatedUser />

Registered User

Checks is the current user is a registered user.

<registeredUser />

User’s email address

Checks if the user’s email address matches a specific pattern.

<email pattern=".*@gmail\.com" />
  • pattern (required): A regular expression of the required email address pattern.

User’s first name

Checks if the user’s first name matches a specific pattern.

<firstName pattern="A.*" />
  • pattern (required): A regular expression of the required first name.

User’s last name

Checks if the user’s last name matches a specific pattern.

<lastName pattern="A.*" />
  • pattern (required): A regular expression of the required last name.

User’s preferred locale

Checks if the user’s preferred locale matches a specific pattern.

<preferredLocale pattern="de_DE" />
  • pattern (required): A regular expression of the required locale.

Callbacks

Check by calling a Eval() method in a custom callback type that implements weweave.DnnDynamicRedirect.Extension.ICallbackRule.

<callback assembly="AssemblyName" type="Full.Qualified.Type.Name" >
  <key>value<key />
<callback />

To allow parameterization, all child nodes of the callback node (the <key> node in this example) are passed as parameters to the custom callback. A custom callback type looks as follows:

namespace Your.Namespace
{
  public class YourCustomCallbackRule : weweave.DnnDynamicRedirect.Extension.ICallbackRule
  {
    public bool Eval(HttpRequestBase request, UserInfo user, XmlNodeList parameters = null)
    {
      // Add your logic here
      return true;
    }
  }
}
  • assembly (required): Name of the assembly.
  • type (required): Full qualified name of the type implementing weweave.DnnDynamicRedirect.Extension.ICallbackRule.

Troubleshooting

Enabling debug logging

Add the following lines right before the closing “</log4net>” to the file DotNetNuke.log4net.config which you’ll find in your website’s root directory.

<logger name="weweave.DnnDynamicRedirect">
    <level value="Debug" />
</logger>

Debug output will be written into the log files in this directory: Portals\_default\Logs

Uninstalling

You can easily remove DNN Dynamic Redirect from your DNN installation by uninstalling the extension.