Triggers and markers reference

Triggers define the way redirection.io agents will match incoming requests before performing an action.

In a Rule, the Triggers are the conditions that incoming HTTP requests must match in order the rule to be applied. For one given incoming HTTP requests, several rules can be matched, if all of their triggers are matched.

redirection.io implements different types of Triggers:

• the URL of the request
• the presence, absence or value of a HTTP request header
• the HTTP method of the request
• the backend response status code that is about to be returned to the user
• the date and the time of the request
• the IP address that performed the request

If you need another type of trigger, feel free to contact us, we welcome every good idea!

The URL trigger

The URL trigger is based on the incoming URL, and can be defined as a simple URL (for example /some/page.html) or a pattern (for example "match all URLs of the form /shop/products.php?id=<INTEGER>).

The source URL trigger is required for all the Rules, in the first step of the Rule creation form:

The "Source URL" value must either start with /, ://, http:// or https://:

• /: this will apply to all the requests for which the URL path matches the Source URL, whatever the scheme and the domain name used. For example, the Source URL /test will be triggered for incoming requests on http://example.com/test or https://example.com/test or https://subdomain.example.org/test
• ://: this will apply to all the requests for which the domain and the URL path match the Source URL, whatever the scheme used. For example, the Source URL ://example.com/test will be triggered for incoming requests on http://example.com/test or https://example.com/test, but not on https://subdomain.example.org/test or http://example.org/test
• http://: this will apply to all the requests for which the domain and the URL path match the Source URL, and performed with the http protocol. For example, the Source URL http://example.com/test will be triggered for incoming requests on http://example.com/test, but not on https://example.com/test or http://example.org/test
• https://: this will apply to all the requests for which the domain and the URL path match the Source URL, and performed with the https protocol. For example, the Source URL https://example.com/test will be triggered for incoming requests on https://example.com/test, but not on http://example.com/test or https://example.org/test

The URL trigger can use markers, which are a powerful way to match several URLs at once, based on patterns. For example, a Rule can be created to redirect all the URLs of the form /shop/products.php?id=<INTEGER> to /shop/clothes/product-<INTEGER>.html, with the status code of your choice. Of course, the rules can embed much more complexity, based on the requirements you choose to apply on the markers.

Under the hood, we use regular expressions to match incoming URLs, but you won't have to write manually these regular expressions. You can instead use our graphical expressions builder, which allows to express complex requirements in a simple way. Read the chapter about markers to understand how they work.

If you want a Rule to be executed for every request to your website, please use a marker of the type anything. You can combine this very permissive URL trigger with more restrictive triggers of other types:

Once added, a marker can be modified by clicking on it:

The Header trigger

The Header trigger allows to select request based on the presence, the absence or the value of a HTTP header in the request. There are many use cases for this header: redirecting the user based on his preferred language (Accept-Language header), run a specific action for a particular User-Agent, etc.

The above example Rule will be triggered for every request arriving on your website with an Accept-Language request header starting with fr- (so, for example, fr-FR,fr;q=0.9,en-US;q=0.8,en;q=0.7,de;q=0.6, but not en-US;q=0.9.

The Method trigger

The Method trigger filters requests based on the HTTP method used for performing the request. You can select one or more HTTP method, and the Rule will be triggered only if the HTTP method used for the request matched one of the selected methods:

This trigger can also be negated, in order to trigger the rule only when the request HTTP method does not match one of the selected HTTP methods:

The Backend Response Status Code trigger

The Backend Response Status Code trigger allows to restrict triggering a Rule based on the Status Code generated by your backend application. When a rule uses the backend response status code trigger, it will first let the request go by to your backend application, and it will inspect the response HTTP status code that your application generated.

This is useful, for example, if you want to execute a specific action when a given Status Code is going to be sent back to the user.

This trigger can also be negated, in order to trigger the rule only when the Status Code that is going to be sent back to the user does not match one of the selected status codes:

The Date, Time and DateTime triggers

This trigger is only available to projects on the "Pro" plan, and requires to use at least the agent 2.6.0.

This time-related triggers family is designed to allow filtering requests based on the date or the time they have been performed. In other words, they allow to execute a rule only on a given day, after or before a date, during a specific timeframe, etc.

For example, one can filter based on the date of the request:

• Equals: the rule will only be triggered if the request date is equal to the configured value.
• Is not equal to: the rule will only be triggered if the request date is different than the configured value.
• Is after: the rule will only be triggered if the request is performed after the date provided.
• Is before: the rule will only be triggered if the request is performed before the date provided.
• Is between: the rule will only be triggered if the request date is between the two dates provided.
• Is not between: the rule will only be triggered if the request date is not between the two dates provided.

One additional criterion is Is one of, which allows to choose which days of the week a rule must be executed.

Look at the following example:

With such a trigger, this rule will be executed for all the requests on /live-meeting performed during weekends. During weekdays, the rule will be skipped.

The Time trigger is similar to the Date trigger, except it allows to define which timerange in the day must trigger the execution of the rule:

The Date, DateTime and Time triggers can be combined:

• a DateTime trigger that would restrict the rule to be applied only after a given date and hour;
• a Date trigger to limit the rule to weekends only;
• à Time trigger to limit the rule only during a given timerange of the day.

The IP address trigger

This trigger is only available to projects on the "Pro" plan, and requires to use at least the agent 2.3.0.

The IP address trigger allows to execute a Rule only if the client IP address matches some restrictions:

• Equals: the rule will only be triggered if the client IP address is equal to the configured value
• Is not equal to: the rule will only be triggered if the client IP address is different than the configured value
• Greater than: the rule will only be triggered if the client IP address is greater than the configured value.
• Greater than or equal: the rule will only be triggered if the client IP address is greater than or equal the configured value.
• Less than: the rule will only be triggered if the client IP address is lower than the configured value.
• Less than or equal: the rule will only be triggered if the client IP address is lower than or equal the configured value.
• In range: the rule will only be triggered if the client IP address is between the two IP addresses provided
• Not in range: the rule will only be triggered if the client IP address is not between the two IP addresses provided

Comparison is done using the IP address notation. For exemple, 10.100.1.1 is greater than 10.9.1.1 (even if this is not true from a string comparison perspective).

The Sampling trigger

This trigger is only available to projects on the "Pro" plan, and requires to use at least the agent 2.3.0.

The Sampling Trigger can be used to execute a Rule only on a given portion of your traffic. For example, if you choose the value 22, then 22% of the matched requests will produce a response containing the actions of this rule.

Creating a marker

As explained above, markers are useful to have one rule apply to several URLs at once, without the need to create several rules. Defining a marker is quite simple:

1. click on the "Add marker" button. A modal window appears, with three tabs.
2. Specify the marker's informations in the "Metadata" tab (name and description of the marker) - this will allow to remind yourself the goal of the marker;
3. The "Restrictions" tab allows to define the marker type and characteristics. You can for instance define string markers, containing only uppercase letters and starting with the FOO string.
4. "Transformations" are an easy way to transform the matched values for reusing them later on, in actions.

Once the marker is created, you can go on and use its value in the "Actions" part of the rule. You can also simply use this marker to match a lot of incoming URLs, without using the marker's value (for instance, you could want to create a "Page not available" action for all the requests of the form /wp-admin/<WHATEVER>.

Hovering on the marker displays the details of the marker, which is useful to understand what this markers does:

Markers types

redirection.io supports a quite large variety of URL markers:

anything

The anything marker will match every characters. It is equivalent to the .* regular expression.

date

The date type stands for a full-date, as per rfc3339.

• Example: 2018-07-15
• Options: none

datetime

The datetime type stands for a date-time, as per rfc3339.

• Examples:
  • 2018-07-15T14:59:12Z
  • 2018-07-15T14:59:12+02:00
  • 2018-07-15T14:59:12.52Z
• Options: none

enum

The enum type allows to list exact accepted values.

• Examples:
  • cat
  • dog
  • fish
  • it can be multiple words
• Options:
  • Values (required): Just type the character or word that the marker must match, and press "enter".

integer

The integer type matches positive integer values (aka. natural numbers).

• Examples:
  • 1
  • 42
  • 67638
• Options:
  • Minimum (optional): You may define a minimal value for the marker to match. For instance, if you type 404 in the "minimum" field, the values 405 and 1234 will be match, but not 88 nor 403. This bound is inclusive (which means, with the previous example, that 404 will be matched).
  • Maximum (optional): You may define a maximal value for the marker to match. For instance, if you type 404 in the "maximum" field, the values 88 and 403 will match, but not 405 or 1234. This bound is inclusive (which means, with the previous example, that 404 will be matched).

regex

This type allows to define advanced matching expressions based on regular expressions. This is of course the most versatile way of creating markers, as it can help create very complex matching expressions.

• Examples:
  • [a-z0-9_-]{3,16}
  • (\d)+
• Options:
  • Regex (required): Type here the regular expression that you want to use during the matching

Whenever possible, please try to use other native types of markers, in order to benefit from the maximal flexibility of the markers system.

We deliberately do not support regular expressions such as "look-ahead" or "look-behind". When used incorrectly, this type of regular expression can severely degrade analysis performance and can even be used for regular expression denial-of-service attacks.

If you need to create an exception, it is highly likely that you can achieve the expected behaviour by creating two rules:

• a "general" rule, which will apply in all cases;
• and a second rule, for the specific case that needs to be the subject of an exception, with a higher priority.

For example, suppose you want to redirect all URLs of the form /redirect-country/<COUNTRY-CODE>, with <COUNTRY-CODE> being a 2-letter code, except for the string "en".

Two strategies are possible:

• either list all possible values (de, uk, us, it, nl, etc.) with an "enum" type marker
• or create two rules:
  • a first generic rule with priority 0, with a URL trigger of the form /redirect-country/<COUNTRY-CODE> in which <COUNTRY-CODE> is defined as a regex marker with the regular expression value [a-zA-Z]{2}.
  • a second rule, with a higher priority (say, 10), triggered by the URL /redirect-country/fr, which uses the "configuration" action to prevent execution of the first rule in this specific case.

In other words, the "configuration" action can "cancel" the application of other rules of lower priority to manage exceptional cases. An example use of the "configuration" application is provided in the "Redirect except a path" recipe.

string

The string type allows to define textual markers, which is the most common case for defining markers. This type should cover most of the matching cases, this is the reason why it is auto-selected when you create a new marker.

We support the full utf-8 range, which means that you can match regular ascii chars, but also emojis or specific alphabetical characters.

• Examples:
  • string
  • h3llo
  • with-specific.chars
  • nón-asçii-chars-Ě-Dž
• Options:
  • lowercase letters (optional): Check this checkbox to match strings containing lowercase letters, as defined in the Unicode General Category Ll.
  • uppercase letters (optional): Check this checkbox to match strings containing uppercase letters, as defined in the Unicode General Categories Lu and Lt
  • digits (optional): Check this checkbox to match strings containing digits (0, 1, 2, ... 9)
  • percent-encoded-chars (optional): Check this checkbox to match strings containing percent encoded characters as per rfc3986.
  • Specific characters (optional): You can add here several specific characters - it can for instance be the underscore char (_), a dash (-), a point (.), etc.
  • Starting With (optional): In combination with other restrictions, this restriction will only match strings starting with this value
  • Ending With (optional): In combination with other restrictions, this restriction will only match strings ending with this value
  • Containing (optional): In combination with other restrictions, this restriction will only match strings containing this value

uuid

The uuid type matches valid uuid-formatted strings.

• Examples:
  • f6883ff9-f163-43d7-8177-bfa24277fd20

Marker transformations

Introduction

The values that have been matched using markers can be reused in actions. For instance, if you defined a URL trigger with a marker named slug, you can choose to create a Redirection action to a url populated with this marker.

Sometimes, however, your URL format has changed. Imagine, for instance, that your previous URLs used to look like:

• http://example.org/some_category/some_product.63664.html
• http://example.org/some_other_category/an_other_product.13719.html
• http://example.org/an_third_category/a_third_product.871.html

While, after your website redesign, your new URLs have been "cleaned" and now look like:

• http://example.org/some-category/some-product
• http://example.org/some-other-category/an-other-product
• http://example.org/an-third-category/a-third-product

(Yeah, this is much more readable)

You may have defined a URL trigger of the form /<CATEGORY_NAME>/<PRODUCT_NAME>.<PRODUCT_ID>.html, where:

• <CATEGORY_NAME> is a string marker matching lowercase letters and the _ sign;
• <PRODUCT_NAME> is a string marker matching lowercase letters and the _ sign;
• <PRODUCT_ID> is an integer marker.

Just enable a Replace transformation on the <CATEGORY_NAME> and <PRODUCT_NAME> markers, and you will be able to reuse those values by injecting them in a Redirection action of the form:

• Status code: 302
• Target URL: /<CATEGORY_NAME>/<PRODUCT_NAME>

Available marker transformation types

redirection.io markers support several transformations:

• Camelize: Transforms strings of the form some-string into someString (works with dashes and underscores)
• Dasherize: Generates a dasherized version of the string, where words are separated with dashes, for example hello-world
• Lowercase: Write all the characters lowercase, for example helloworld
• Replace: Replaces all the occurrences of a string with another one (for instance, transform st-petersburg to saint-petersburg)
• Slice: Slices the string from one position (starting at 0) to another (this can be useful, for example, if your marker values have been truncated)
• Underscorize: Generates a underscorized version of the string, where words are separated with underscores, for example hello_world
• Uppercase: Write all the characters uppercase, for example HELLO-WORLD

Chain the marker transformations

All these transformations can be chained and are executed sequentially, which means that you can for example successively apply a Replace transform, then a Camelize one:

st-petersburg ➡️ saint-petersburg ➡️ saintPetersburg

Marker templates

It may happen that many rules in your ruleset use the same marker. For example, imagine that you need to define a rule that contains a country parameter, whose value can be de, es, fr, it, uk or us. You would usually do this using an enum marker type with these values.

If, however, you need to define many rules containing the same marker, it can become a bit repetitive to re-create this marker in all these rules. This is where marker templates come into play, allowing you to define markers that can be reused in multiple rules without the need to re-define them each time.

To learn more about marker templates, see the project configuration section of our documentation.

Are you up-to-date with triggers and markers? Go on with creating an action.