Create a rule

Some concepts : rules and ruleset

A rule is basically made of two items:

  • a Trigger, which defines the conditions when the rule must be executed ;
  • an Action, which defines which operations the rule must perform.

It is also possible to associate Examples to a rule, which help test and check the result of the rule, in a similar way to unit tests.

The complete list of Rules is called the Ruleset. When you publish a Ruleset, it gets applied to your website, which means that every request made to your website is filtered against the Ruleset. In other words, for each request performed to your site, the redirectionio-agent installed in your infrastructure evaluates which Rules must be executed for this request.


Triggers define the way agents will match incoming requests before performing an action. Triggers are based on the request URL pattern, and can include several other conditions: HTTP method, HTTP headers, etc. See the Triggers and markers reference page for more information.


When a rule is triggered by a request, one or several Actions can be executed. Of course, the main purpose of is to run redirections, but we can do much more! Here is the list of the cumulative actions that can execute:

  • Redirection: execute an HTTP redirection;
  • Page not available: return an HTTP error, for urls that you knowingly want to disable (404 or 410);
  • HTML Meta-Tag override: to define default meta tags, or override existing meta tags;
  • Custom HTTP response headers: to add or override one or several HTTP headers;
  • Structured data: this action allows to inject structured data within the page body;
  • Custom HTML Code: this action allows to inject custom HTML code in the page.

All those actions are precisely defined in the Actions reference page.

How to create a rule

Of course, creating and managing rules is the way to go in order to benefit from Creating rules is rather easy and straightforward:

  1. project dashboardhead to the dashboard of your project

  2. Rules menuhit the "Rules" menu link

  3. Button to add a new ruleclick the "Add a new rule" link, on the upper right corner of the page

  4. Rule creation formthe rules creation form is divided into four parts:

    • a Trigger section allows to configure the conditions that will trigger the execution of the rule;
    • Examples allow to attach example requests to this rule. These examples will be used in the Impact step, to check that the rule behaves like you expect it. If your project has already logged some traffic, examples can be generated based on your real traffic logs;
    • the Action step allows to define which actions must be executed when the rule is triggered;
    • the Impact step displays how the rule will behave, once published.

    You may use the "Add marker" button to insert markers in the "Source URL". Markers are re-usable items that we will collect parts of the incoming URL. For example, if the URL to match is of the form /shop/products/<ID> with <ID> an integer, you can type /shop/products/and then hit the "Add marker" button, and insert an "integer" marker (name it as you like). In the "Action" section, you can then use this newly created marker to re-inject it in the redirection target. Read more on markers

  5. Impact resultsOnce the Triggers, Examples and Actions have been configured, look at the Impact section. It explains how the rule behaves against the examples configured at the second step. You can examine the impacts for each sample request, in order to understand how the response for that request was handled.

  6. If everything looks right, click the "Save this rule" button. The rule will be saved, but won't be immediately applied to your production: your first have to "publish" the changes.

Temporarily enable or disable a rule

In certain circumstances, you may need to disable a rule for a temporary period. You could delete the rule altogether, as it is always possible to re-add it later using imports or using the rules version history, but we offer a more straightforward convenience for such cases.

In the "Impact" step, you can choose to enable or disable a rule. If a rule is disabled, it will not be used by your instances (both "production" and "test" instances). It will still exist, and you can re-enable it when needed, but it will simply have no impact on your website, as if it did not exist.

Enable or disable a rule in a quick way

In the rules list, you can filter the rules list using the "Enabled" filter. This can be helpful to retrieve a set of disabled rules that you want to re-enable.

Ruleset settings

These settings are available if your project uses an agent version at least 2.1.0.

When writing a set of redirection rules for your website, you may want to configure some common behavior for your rules. While we usually follow the Standards and RFC, these might not always perfectly fit business or real-world requirements.

Under the "Settings > Features" menu of a project, you can change the following parameters:

Ruleset behavior configuration

ignore URLS case

The ignore URLS case setting is disabled by default when a project is newly created, and can be changed by project publishers.

If it is disabled, URLs in different cases are considered to be different resources (which follows the standards). This means that, if you create a redirection for the url /test, it will not redirect a request to /TEST.

Enabling this setting changes the behavior, as the redirection agent will ignore the request URL case when matching it against you ruleset. In other words, if this setting is enabled, a redirection rule for the url /test will also redirect a request to /TEST.

ignore marketing query parameters in matching

This setting is enabled by default for all newly created projects, and can be changed by project publishers.

Marketing parameters are URL query parameters that are very commonly used in marketing, to track how online marketing campaigns are effective. There are 5 parameters frequently used:

Parameter name Purpose Required Example
utm_source Identify the advertiser, site, publication, etc. that is sending traffic Yes utm_source=google
utm_medium Identify the advertising or marketing medium type (email, cpc, banner, etc.) Yes utm_medium=cpc
utm_campaign Identify the name of the campaign or the product promotion Yes utm_campaign=winter-sale
utm_term Identify the search keywords No utm_term=cookbook
utm_content Identify the specific link that was clicked to bring the user to the page No utm_content=footer-link

While these query parameters provide very useful informations for marketing purpose, the produce different URLs, from a strictly technical point of view. In other words, as per the standards, there is no reason to consider that the URLs /test and /test?utm_source=google refer to the same resource. However, the real-life proves that, if you have setup a redirection rule for the url /test, you will usually want that a request to /test?utm_source=google is also redirected.

This is exactly what enabling this setting allows: when enabled, the query parameters will be ignored when trying to find a redirection rule that matches the request. If your marketing campaigns require other query parameters, it is possible to add them in the "marketing query params" field.

pass marketing query parameters to the redirection target

This setting is enabled by default for all newly created projects, and can be changed by project publishers.

When the previous setting is enabled, this setting allows to pass the catched marketing parameters to the redirection target. For example, imagine that your ruleset contains a rule redirecting requests from /test to the target URL /example. With this setting enabled, a request to /test?utm_source=google will get redirected to /example?utm_source=google. If disabled, the redirection will be performed to /example (without the marketing query parameters).

Marker templates

Marker templates are useful to define project-wide markers, that can easily be reused from one rule to another. For example, imagine that you need to define several rules containing a country parameter, which value can be de, es, fr, it, uk or us. It can be a bit repetitive to re-create the same marker in all of these rules.

Marker templates are useful in such a case, as they allow to define markers that can be used in several rules, without the need to re-define it each time.

Setting-up marker templates can be done in a few clicks:

  1. project settings, marker templates listIn the settings of your project, under the "features" tab, locate the "Marker templates" section
  2. Hit the "Add a new marker template" button, this opens a form in the lateral panel
  3. project settings, marker template creation formFill the marker template creation form:
    • define a "CSV name: this string will be used when importing rules. Each occurrence of this string will be replaced with a marker of this type;
    • the "Marker name" is the unique name for this marker template;
    • fill the "restrictions" and "transformations" tabs to define how this marker should behave.

Once a marker template has been defined, you can use it in the rule creation form: using a marker template in a rule If the definition of this "country" marker changes, simply head to the marker template settings and edit the template; you will be proposed to update all the associated rules too.

You may also want to change this marker for one rule only - simply click on the marker name within the rule edition form, and you will be proposed to "unlink" this marker from the marker template:

Unlink a marker instance from the associated marker template

Changes publication and history

Once you have made several changes to your ruleset, you may want to apply these changes on your production instances:

  1. Ruleset changes reviewlook at the top of the screen: the orange bar shows that there are unpublished changes in your draft ruleset. This means that new rules have been created, but are still not published - they are invisible to the agent instances. The changed rules are tagged with a "DRAFT" badge and are always displayed as the first items in the list of rules, regardless of the defined sort order.
  2. Ruleset changes publicationonce you have reviewed the changes, you may publish them using the "Publish changes" button. This will ask for an optional publication comment, the right place to explain what you just did for later understanding.
  3. after a few seconds, depending on your plan, the new rules should be applied to your instances. Head to the project's "instances" screen, you should be able to see which instances are up-to-date.

When are my rules applied ?

Your newly created redirection rules should be applied on your website after a short delay - usually about 20 seconds. You may want to check which agents are up-to-date on your project's "instances" screen, which lists running instances, when they have been updated, and how many rules they are using.

This page has been updated on March 28th, 2024.
Can't find your answer?