Fallback Redirects

Fallback redirects are based on regular expressions and can be used to redirect whole groups of pages, handle migration scenarios, or create the impression of a certain structure.

They fire exclusively when the request would have otherwise been a 404.

They can not be used to overwrite other working URLs. For example, defining a fallback for a path under which an article exists will have no effect. Also, literal redirects will always take precedence over fallback redirects.

If a fallback redirect is resolved to a target that would also result in a 404, Viewport will directly respond with a 404 and not send a redirect.

Create and Edit a Fallback Redirect

You can create and manage redirects for your Scroll Viewport site under Site Settings:

Select your site in your site overview screen (if you have multiple sites).
Click Settings from the top right of the single site overview screen.
Click Manage next to Redirect(s). You will see a list of all redirects that were already created for your site.
Select the Advanced checkbox in the top right. The redirect editor opens:
Enter your redirects in the permitted format (see next section for more details).
Click Save. The redirect option in Site Settings will state Active Redirect(s).
Click Close.
Click Update site and Go Live to activate your newly created redirect.

Saving or deleting redirects in your site settings won’t affect your live site until you go live with the changes.

Permitted Values

When using the configuration field in the advanced redirect mode, you will need to make sure to follow a set format and stick to the permitted values.

To setup a new redirect you should always use the following format:

<mode> <source> <target> <type>

For a fallback redirect, choose from the permitted values in the table below.

Required format:

Mode

Source

Target

Type

Permitted values:

fallback

Relative path of the Viewport site URL with regular expression capture groups.

Can contain path segment capture groups ([^/]+).

Must end with /(.+).

For internal Viewport site URLs: relative path
For external URLs: absolute path starting with //

Fallback redirect targets can make use of back references and chaining.

permanent
temporary

Some helpful tips for creating fallback redirects:

For protocol-relative links (links that should remain https), you can write //www.example.com as a short-form of https://www.example.com.
If multiple fallback rules match a path the first match will fire. Put your most specific rules first.
Consider if you need additional literal redirects for paths which can’t be covered by fallback redirects. In the example below you might want to set up a literal redirect for /my-path/.
Scroll Viewport site URLs that are set as a redirect target can contain query parameters, such as in-app help query ?inAppHelp=true. The last regex group of a fallback rule also matches query parameters. Use a back reference in the target like in the example below to make sure query parameters are not lost.

Example of allowed redirects

CODE

fallback /my-path/(.+) /new-path/$1 temporary

Disallowed Redirects

To prevent your users entering endless loops of redirects, we have placed the following limitations when creating redirects:

source and target value can’t be the same path

Disallowed paths

Redirecting from the site preview, root page or the search of your Scroll Viewport site is not possible. They correspond to the following disallowed paths:

/_search*
/preview*
/

Regular Expressions and Back References

Fallback redirects use regular expressions (regex) to find out whether a specific rule applies to a given URL. For example, /content-source/(.+) will match on all paths starting with /content-source/. It has one group (.+) which will match on any character, appearing at least one time.

The value that the group matches on can be reused in the target via back references. Back references start with a $ followed by the index of the group they reference. For example, $1 to reference the value of the first group. $0 is a special case that references the whole match, so the full path of the request.

There are two types of capture groups which are allowed in fallback redirect rules:

/([^/]+)/ for matching a single path segment.
/(.+) for matching everything after the final slash (required at the end of a rule).

Note that Scroll Viewport uses Java-flavored regular expressions.

Example with single back reference

CODE

fallback /some-path/(.+) /other-path/$1 permanent

The rule will match on any path starting with /some-path/. It has one group (.+) which will match on any character, appearing at least one times. This results in the following behavior.

Users navigates to: /some-path/article?inAppHelp=true
Viewport redirects to: /other-path/article?inAppHelp=true

Note that this will only redirect users visiting paths with at least one path segment after /some-path. If you also want to redirect users going directly to /some-path, consider adding an additional literal redirect:

CODE

literal /some-path /other-path permanent

Example with multiple back references

CODE

fallback /source/([^/]+)/(.+) /source/$1/inserted-path-segment/$2 permanent

The rule will match on any path starting with /source/. The first group will match on a group of characters that does not contain a /. The second group will match on any character, appearing at least one times. This results in the following behavior:

Users navigates to: /source/latest/article
Viewport redirects to: /source/latest/inserted-path-segment/article

Chaining Fallback Redirects

You can combine multiple fallback redirects into a chain. When a fallback redirect is applied to a path and the resulting target is not available, Viewport will attempt to redirect the target yet again until it finds a resource that is available. This is useful when the page you want to redirect to might be available under one of several paths, as might be the case when using variants.

For instance, consider the following rules:

CODE

fallback /os/(.+) /os/windows/$1 permanent
fallback /os/windows/(.+) /os/macos/$1 permanent
fallback /os/macos/(.+) /os/linux/$1 permanent

Assuming, that the article the-linux-kernel is only available under the /os/linux/ path, if a user visits /os/the-linux-kernel the following chain of redirects will be executed:

/os/the-linux-kernel → /os/windows/the-linux-kernel
/os/windows/the-linux-kernel → /os/macos/the-linux-kernel
/os/macos/the-linux-kernel → /os/linux/the-linux-kernel

If a redirect chain exceeds 10 steps, no resource is found, or if for a target Viewport can’t find another redirect, it will respond with a 404.

Fallback Redirects Limitations

In order to keep redirects fast and stable we have set the following limits in place:

A fallback redirect target can contain 5 back references at most. If a rule has more than 5 back references it will be ignored.
If you use a back reference with an index that does not exist, the rule will be ignored.
Fallback redirect chains with more than 10 steps will result in a 404.
If a fallback redirect rule produces an URL longer than 2048 characters, it will be discarded and Viewport will respond with a 404.

Escaping period/dots in the redirect

Dots in the source URL of your redirect can be escaped with a \. Add the character right before the period, like this:

/content-source/v1\.0/(.+) /documentation/current/$1 permanent