1. Building Sites with Oracle Content Management
  2. Publishing and Managing Sites
  3. Use Site Redirects or URL Mapping
  4. Specify Redirect Rules in a JSON File

Specify Redirect Rules in a JSON File

You can specify redirect rules for URLs in a JSON file.

Use the following format in a JSON file to specify redirect rules for URLs.

{
	 "redirectRules":
	 [
		{
			"type": "string",
			"comment": "this rule is applied first",
			"expression": "/index.htm",
			"location": "/home.html"
		},
		{
			"type": "wildcard",
			"expression": "/items/*?page=*",
			"location": "/<$page$>?item=<$wildcard(1)$>",
			"code": 302
		}
	]
}

The outer containing structure in the JSON file is an array. The array contains rule instances.

The "string" rules will be evaluated first, followed by the "wildcard" rules, in order. Once one of the rules matches, the evaluation of subsequent rules is abandoned, and the corresponding redirect is generated.

Each rule has the following properties:

  • The "type” property is an optional string that indicates the type of redirect rule. The value must be one of the following strings:

    • "string" specifies a faster rule whose expression matches the entire input URL exactly.

    • "wildcard" specifies a wildcard rule that can match a number of URLs. This is the default value if the property is omitted.

  • The "expression" property is a required string that matches against the incoming site-relative URL. In a wildcard rule, the asterisk (*) token matches zero or more characters.

  • The "location" property is a required string that indicates the location or destination of the redirect. The redirect can be a full or relative URL.

  • The "comment" property is an optional string that has no impact upon the evaluation of the rules. It includes notes or commentary.

  • The "code" property is an optional integer that provides the HTTP response code to use when issuing the redirect. The value must be one of the following integers:

    • 301: Indicates that the resource moved permanently. This is the default value if the "code" property is omitted.

    • 302: Indicates that the resource moved temporarily.

  • Only "wildcard" rules can have the "flags" property. The two legal flags are "globstar" and "caseinsensitive", separated by comma. The "globstar" flag changes the way that the "*" matches in a wildcard rule "expression". Normally, the "*" matches all possible characters. When "globstar" is set, the "*" matches until the next "/" character in the URL. By default, expression matching is case sensitive unless the flags value includes caseinsensitive.
  • The "enabled" property is an optional property used to enable or disable the rule. It can be true or false. The default value is true.

Location Tokens

You can use location tokens to help manufacture a redirect location. Each of the following location tokens can help specify a redirect:

  • <$urlPath$>: The path portion of the matching URL.

  • <$urlQueryString$>: The entire URL query string from the matching URL.

  • <$urlQueryStringExcept(name1,name2)$>: The entire URL query string from the matching URL minus the named parameters.

  • <$wildcard(N)$>: The one-based index of the matching wildcard in the matching URL. (This is analogous to \1..\9 in regular expressions.)

  • <$name$>: The value of the named query string parameter. For example, if you have the query string msmith: ?page=42 on the input, then you can use <$page$> in the location to put '42' into the location.

Restrictions

The following restrictions apply to the redirects.json file as a whole and to the rules it contains:

  • The maximum overall file size accepted by Oracle Content Management is 250 KB.

  • The maximum number of rules in the redirects.json file is 1,000.

  • The maximum "expression" length for a rule is 1,000 characters.

  • The maximum "location" length for a rule is 2,000 characters.

  • The maximum number of '*' tokens in a wildcard rule expression is 10.

String Matching Example

Rule:

        {
              "type": "string",
              "expression": "/old/page.jsp?id=material&type=glass",
              "location": "/new/<$id$>.htm"
        }

The following URL would match the rule:

/old/page.jsp?id=material&type=glass

  • The resulting location would be: /new/material.htm

  • The entire URL matches, including the query string.

  • Although <$id$> is used in the location, it is not necessary for this example because only one possible query string could match. The location could have been written as /new/material.htm.

The following URLs would not match the rule:

  • /old/page.jsp

    (The rule’s expression gives a query string that must match.)

  • /old/page.jsp?id=material&type=glass&index=2

    (The extra &index=2 in the candidate URL does not exactly match the rule expression.)

  • /old/page.jsp?type=glass&id=material

    (The ordering of query string parameters must match in a “string” rule.)

Wildcard Matching Example

Rule:

        {
              "type": "wildcard",
              "expression": "/old/*/pages/*?id=*&item=sheet-*",
              "location": "/new/<$id$>/<$wildcard(4)$>.html"
        }

The following URLs would match the rule:

  • /old/phones/android/pages/info.asp?id=XT1045&item=sheet-specs

    • The resulting location would be: /new/XT1045/specs.html

    • The path portion of the URL matches, so the query string is also examined for matching conditions.

    • The parameters in this example happen to match the ordering of the parameters in the rule expression, but this is not required.

  • /old/phones/android/pages/info.asp?item=sheet-specs&id=XT1045

    • The resulting location would be: /new/XT1045/specs.html

    • The path portion of the URL matches the rule expression before the question mark (?), so the parameters are also checked for a match.

    • Although the parameters are listed in a different order in the rule expression, the parameters are matched individually.

  • /old/phones/android/pages/info.asp?id=XT1045&item=sheet-specs&unrelated=thing

    • The resulting location would be: /new/XT1045/specs.html

    • The path portion of the URL matches, so the query string is also examined for matching conditions.

    • The candidate URL has an extra &unrelated=thing parameter, but since the named query parameters in the rule expression match, the rule is deemed to match.

    • The unrelated parameter would be available in the location as a token, as <$unrelated$>, and would have the value thing, even though it did not contribute to the match of the rule.

The following URLs would not match:

  • /old/pages/info.jsp

    (The path portion of the URL does not match the path portion of the rule expression.)

  • /old/phones/android/pages/info.asp

    (The path portion of the URL matches the path portion of the rule expression, but the query parameters in the rule expression do not match.)

  • /old/phones/android/pages/info.asp?id=cellular

    (The path portion of the URL matches the path portion of the rule expression, but not all of the query parameters in the rule expression match.)

Defining a Token Array

You can also create an array of token definitions within the redirects.json file to help when configuring redirects that support multiple vanity URLs. This allows you to redirect appropriately based upon the characteristics of the incoming URL.

Use the following format in the redirects.json file to define tokens for use in redirect rules URLs. 

{
	 "tokenDefinitions":
	 [
		{
			"token": "sitePrefix",
			"type": "hostmatch",
			"expression": "example.com",
			"value": ""
		},
		{
			"token": "sitePrefix",
			"type": "hostmatch",
			"expression": "*.com",
			"value": "/site/Starter-Site"
		},
		{
			"token": "gotoRedirect",
			"type": "pathmatch",
			"expression": "*oracle*",
			"value": "https://www.oracle.com",
			"flags": "caseinsensitive"
		}		
	]
}

The tokenDefinitions have the following properties:

  • "type": One of the following:

    • "hostmatch" to match the incoming URL's host value.

    • "pathmatch" to match the incoming URL's pathname value.

    • "querymatch" to match the incoming URL's query value.

  • "token": The name of the token to define.

  • "expression": The expression that should be used for matching. Wildcard characters are supported.

  • "value": The value that should be used for the token.

  • "comment": This is an optional property used to explain or annotate the token definition.
  • "flags": The two legal flags are "globstar" and "caseinsensitive", separated by comma. The "globstar" flag changes the way that the "*" matches in a token. Normally, the "*" matches all possible characters. When "globstar" is set, the "*" matches until the next "/" character in the URL. By default, expression matching is case sensitive unless the flags value includes caseinsensitive.
  • "enabled": This is an optional property used to enable or disable the token. It can be true or false. The default value is true.

When computing the value of a token, the tokenDefinitions array will be enumerated in order. The first matching definition will be used. If no token definitions satisfy the token, then an empty string will be used instead. For expediency and performance, commonly used tokens should be placed at the top of the tokenDefinitions list.

The tokenDefinitions have the following constraints:

  • You can create up to 250 token definitions.

  • The token name must be less than 100 characters.

  • The expression can have up to 10 wildcards.

  • The expression must be less than 1000 characters.

  • The value must be less than 1000 characters.

Example

For example, you may have the following redirects.json file:

{
	 "redirectRules":
	 [
		{
			"type": "string",
			"expression": "/legacy-privacy-policy.html",
			"location": "<$pathPrefix$>/about/new-privacy-policy.html"
		}		
	],
	 "tokenDefinitions":
	 [
		{
			"token": "pathPrefix",
			"type": "hostmatch",
			"expression": "vanity.com",
			"value": "/fashion"
		}						
	]
}

In this case the rule's location property has a <$pathPrefix$> token. The pathPrefix token is defined in the tokenDefinitions section. If the incoming URL matches "vanity.com", then the pathPrefix value will be set to /fashion. This will be used in the location response, resulting in /fashion/about/new-privacy-policy.html.

Let's assume the first vanity domain URL is http://example.com/legacy-privacy-policy.html. This would match the first and only redirect rule.

The declared location for this rule is <$pathPrefix$>/about/new-privacy-policy.html. In this situation, the <$pathPrefix$> token needs to be evaluated. In order to do that the tokenDefinitions array is enumerated to find a match.

The first token definition is considered. Its token is the desired one, so it is further evaluated. The expression vanity.com does not match the incoming URL's example.com so this definition does not satisfy the requirements and the enumeration continues.

At this point there are no more token definitions, so the empty string is used for the value of the <$pathPrefix$> token. The final location returned for this redirect is /about/new-privacy-policy.html.

Let's assume the second vanity domain URL is http://vanity.com/legacy-privacy-policy.html. As with the first URL, the declared location for this rule is <$pathPrefix$>/about/new-privacy-policy.html. In this situation, the <$pathPrefix$> token needs to be evaluated. In order to do that the tokenDefinitions array is enumerated to find a match.

The first token definition is considered. As before, its token is the desired one, so it is further evaluated. The expression vanity.com does match the incoming URL's vanity.com so this definition does satisfy the requirements and the value /fashion is used as the token's value.

Because a match for the token was found, enumeration of the token definitions array stops, and the final location is computed as /fashion/about/new-privacy-policy.html.

Testing Site Redirects

You can test site redirects when editing a site by opening the Settings panel and clicking Redirects. Enter a URL to test and click Test.

Redirects Test Panel