---
title: Manage trigger rules
slug: '3413'
canonical_url: https://docs.coveo.com/en/3413/
collection: tune-relevance
source_format: adoc
---
# Manage trigger rules
[trigger](https://docs.coveo.com/en/2792/) [rules](https://docs.coveo.com/en/236/) define an action to execute in a [search interface](https://docs.coveo.com/en/2741/) when a [query](https://docs.coveo.com/en/231/) meets the associated [conditions](https://docs.coveo.com/en/2793/).
By default, the list of [query pipeline](https://docs.coveo.com/en/180/) triggers for a Coveo [organization](https://docs.coveo.com/en/185/) is empty.
When you add a trigger rule to a query pipeline, an object representing the action to perform is generated inside the `triggers` property of the query response.

The search interface from which the query originates is then responsible for translating this object into an action (for example, [executing a corresponding JavaScript function call](#execute) or [redirecting the web browser to a specific URL](#redirect)).

## Prerequisites

Before creating a rule, make sure that you have the following:

* Access to a search page

You need access to a Coveo-powered [search interface](https://docs.coveo.com/en/2741/) to be able to test the [rule](https://docs.coveo.com/en/236/) that you create.

* An existing query pipeline

The queries from the search page must travel through a specific [query pipeline](https://docs.coveo.com/en/180/).

* Required privileges

You need specific [privileges to be able to add and edit rules in a query pipeline](#required-privileges).

Once you meet these requirements, you can create a rule on the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page.
To test the rule, [use the A/B test feature](https://docs.coveo.com/en/3255/) to compare the results of the rule with the results of the original pipeline.

## Access the "Triggers" subtab

To manage trigger rules, [access the **Triggers** subtab](#access-the-triggers-subtab) of the [query pipeline](https://docs.coveo.com/en/180/) you want to manage.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to manage rules, and then click **Edit components** in the Action bar.

. On the page that opens, select the **Advanced** tab.

. On the **Advanced** tab, on the left side of the page, select **Triggers**.
The **Triggers** subtab appears.

## Add or edit trigger rules

. [Access the **Triggers** subtab](#access-the-triggers-subtab) in the query pipeline you want to manage, then do one of the following:

* To add a new trigger rule, click **Add trigger rule**.

> **Notes**
>
> * When adding a trigger rule for the first time, you can also click **Add rule with code** to define the rule using the appropriate [QPL syntax](#qpl-syntax).
> * When adding a trigger to a list of existing rules, you can also click [dots], and then click **Add rule with code**.

* To edit an existing trigger rule, click the rule you want to edit, and then click **Edit** in the Action bar.

> **Note**
>
> You can also click **More**, and then select **Edit code** to edit the rule using the appropriate [QPL syntax](#qpl-syntax).

. In the **Add/Edit a trigger rule** subpage, under **Type**, select one of the available methods.

. In the box that opens, depending on the selected method, enter the desired value.

* For [**Notify**](#notify), in the **String** box, enter a message to display in the search interface.
* For [**Query**](#query), in the **Query** box, enter a query to perform as a new search in the search interface.
* For [**Execute**](#execute), in the **Function** box, enter a JavaScript function to execute in the user's browser.
* For [**Redirect**](#redirect), in the **URL** box, enter a URL to redirect the user.

. Under **Condition**, select a [query pipeline condition](https://docs.coveo.com/en/2793/) in the dropdown menu or [create a new one](https://docs.coveo.com/en/1959#create-a-condition).

> **Important**
>
> If a trigger rule isn't associated with a query pipeline condition, the rule is ignored.

. Under **Description**, optionally enter information that will help you manage the rule in the future.

. Click **Add rule** or **Save**.

## Duplicate trigger rules

You can duplicate trigger rules within the same pipeline.

. [Access the **Triggers** subtab](#access-the-triggers-subtab) of the query pipeline you want to manage.

. In the **Triggers** subtab, select the rules you want to duplicate within the same pipeline.

. In the **Action** bar, click **Duplicate**.

The duplicated trigger rules appear at the bottom of the list in the pipeline component tab.

## Copy trigger rules to another pipeline

When you have more than one query pipeline that serve different purposes but require similar rules, you may want to copy trigger rules from one pipeline to another.

. [Access the **Triggers** subtab](#access-the-triggers-subtab) in the query pipeline you want to manage.

. In the **Triggers** subtab, select the rules you want to copy to another pipeline.

. In the **Action** bar, click **More**, and then click **Copy to...**.

. In the dialog that appears, select the target pipeline to which you want to copy the rules, and then click **Copy**.

Your copied rules will take effect immediately in the target pipeline.

## Delete trigger rules

. [Access the **Triggers** subtab](#access-the-triggers-subtab) of the query pipeline you want to manage.

. In the **Triggers** subtab, select the rules you want to delete.

. In the **Action** bar, click **More**, and then **Delete**.

. Click **Delete** to confirm.

Your deleted rules will stop being effective immediately in the target pipeline.

> **Tip**
>
> * To avoid undesired search behaviors, delete unused query pipeline rules, as they can impact search relevance.
> 
> * Consider using the [Groups & Campaigns feature](https://docs.coveo.com/en/3283/) to make query pipeline rules only apply for a specific time period.

## Change the rule order

Query pipeline rules are executed in the order in which they appear on the page until a condition is satisfied.

. On the [**Query Pipelines**](https://platform.cloud.coveo.com/admin/#/orgid/search/pipelines/) ([platform-ca](https://platform-ca.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-eu](https://platform-eu.cloud.coveo.com/admin/#/orgid/search/pipelines/) | [platform-au](https://platform-au.cloud.coveo.com/admin/#/orgid/search/pipelines/)) page, click the query pipeline for which you want to manage the rules' execution order, and then click **Edit components** in the Action bar.

. On the page that opens, select the trigger tab.

. In the trigger tab, on the left side of the page, select pass:q,a[**trigger**].

. In the pass:q,a[**trigger**] subtab, click the rule whose position you want to change.

. In the Action bar, click **Move up** or **Move down** to change the position of the rule.

> **Note**
>
> When you move a trigger rule, only the order of execution of trigger rules is adjusted.
> Moving the rule doesn't affect the [order of execution](#order-of-execution) of trigger rules relative to other query pipeline components.

## When and why to use trigger rules

This section explains the different trigger rule methods and provides examples on how to use them.

* [**Notify**](#notify)

* [**Query**](#query)

* [**Execute**](#execute)

* [**Redirect**](#redirect)

### Notify

Use the **Notify** trigger rule when you want to display notifications in the search interface based on specific queries.
This method is useful when you want to inform users about important information and additional context related to their search.
Common use cases include displaying alerts, tips, or disclaimers depending on the user's query.

**Example**

In your medical information website, when a user asks a specific question, you want to show a notification that suggests submitting a consultation request with a healthcare professional.
You create a **Notify** trigger rule that displays the message `For more personalized advice, consider submitting a consultation request with one of our healthcare professionals.` whenever a user performs a query containing the words `symptoms` and `treatment`.

> **Notes**
>
> * If you're using the [Coveo Atomic library](https://docs.coveo.com/en/lcdf0264/), use the [`atomic-notifications`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-notifications\--docs) component to handle notifications generated by the notify triggers.
> For example, you manage an internal search page for equipment parts, where each part is further categorized by model numbers.
> Each time a query is performed without a model number, you want to show `Add a model number to your query` to the user.
> Therefore, you create a **Notify** trigger rule that displays this message.
>  
> ![Notification displayed in a search page using the atomic-notification component | Coveo](:https://docs.coveo.com/en/assets/images/tune-relevance/notify-example.png)
> 
> * If you're using the [Coveo Headless library](https://docs.coveo.com/en/lcdf0493/), use the [`NotifyTrigger`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.NotifyTrigger.html) controller to implement notify triggers.

#### Reporting on notification clicks

You may want to capture information about clicks made by your end users on notification links.

For example, if you have a **Notify** trigger rule that displays a link when end users perform a certain query, you might want to capture information about its usage and leverage it in [Coveo Analytics reports](https://docs.coveo.com/en/266/).

The approach to capture notification link clicks differs depending on whether the links redirect to [items](https://docs.coveo.com/en/210/) in your [index](https://docs.coveo.com/en/204/) or external resources (that is, resources that aren't in your index):

* When notification links redirect to [items](https://docs.coveo.com/en/210/) in the [index](https://docs.coveo.com/en/204/), [log these clicks as regular click events](https://docs.coveo.com/en/2064/).

These clicks are taken into account in the [Search Event Clickthrough](https://docs.coveo.com/en/2837/) [metric](https://docs.coveo.com/en/263/) and [Coveo Machine Learning (Coveo ML)](https://docs.coveo.com/en/188/) [Automatic Relevance Tuning (ART)](https://docs.coveo.com/en/1013/) [models](https://docs.coveo.com/en/1012/) can learn from them.

* When notification links redirect to external resources, the best approach is to log these clicks as [custom events](https://docs.coveo.com/en/2650/).

Since the resources aren't in your index, you don't have all the information necessary to send the [required request body properties](https://docs.coveo.com/en/2064#required-request-body-properties) to the Coveo UA Write API when logging click events.

When logging notification clicks as custom events, consider that:

** These events can't be used by Coveo ML ART models.

** To calculate the [Search Event Clickthrough](https://docs.coveo.com/en/2837/) rate related to these clicks, use [report cards](https://docs.coveo.com/en/267/).
The default [Search Event Clickthrough metric](https://docs.coveo.com/en/2041#search-event-clickthrough) can't be used since clicks logged as custom events aren't considered as regular click events from a Coveo UA perspective.

For example, you could have one [metric card](https://docs.coveo.com/en/1972#metric) showing the number of times the notification link was shown (query count), one metric card showing the number of notification links (click count), and one [calculated metric card](https://docs.coveo.com/en/1972#calculated-metric) dividing the click count by the query count multiplied by 100.

![clickthrough usage analytics metric cards](https://docs.coveo.com/en/assets/images/tune-relevance/notification-clickthrough-example.png)

> **Leading practice**
>
> Considering these facts, add these external resources to your Coveo index.
> This way, you could use these clicks to feed Coveo ML ART models and a default metric to report on the [clickthrough](https://docs.coveo.com/en/2041#search-event-clickthrough) rate.

### Query

Use the **Query** trigger rule when you want to automatically modify or replace certain queries to improve search results.
This method is useful when users commonly submit incomplete or inconsistent queries, and you want to improve result relevance without requiring manual refinement.
Common use cases include correcting frequent search patterns, expanding queries to include related terms, or guiding users toward more precise queries.

**Example**

You manage a support portal where you notice that users often search for `password reset` when they actually need to complete the 2FA process.
You create a **Query** trigger rule that performs the `how do I log in` query whenever a user searches for `password reset`, ensuring that support articles with relevant log-in steps are displayed.

> **Notes**
>
> * For the [Coveo Atomic library](https://docs.coveo.com/en/lcdf0264/), the [`atomic-did-you-mean`](https://static.cloud.coveo.com/atomic/v3/storybook/index.html?path=/docs/atomic-did-you-mean\--docs) component is used to display changes made to the user's query by a query trigger.
>  
> ![Query trigger change displayed in a search page using the atomic-did-you-mean component | Coveo](:https://docs.coveo.com/en/assets/images/tune-relevance/query-example.png)
> 
> * If you're using the [Coveo Headless library](https://docs.coveo.com/en/lcdf0493/), use the [`QueryTrigger`](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.QueryTrigger.html) controller to implement query triggers.

### Execute

Use the **Execute** trigger rule when you want to run custom logic in the search interface based on specific queries.
This method is useful when the desired action can't be achieved by displaying a notification, modifying the query, or redirecting the user.
Common use cases include triggering custom warnings, displaying modal dialogs, or enforcing specific workflows based on what users search for.

**Example**

You manage a support portal and you recently deprecated the **ACME CTRLR** product.
You realize that support agents, however, are still searching for this product name.
You create an **Execute** trigger rule that runs a `deprecatedProduct()` JavaScript function whenever a user searches for `acme ctrlr` (or any casing variation), ensuring that agents are alerted that the product has been deprecated.

![Execute trigger rule in the Administration Console](https://docs.coveo.com/en/assets/images/tune-relevance/execute-example.png)

> **Notes**
>
> * The [Coveo Headless library](https://docs.coveo.com/en/lcdf0493/) [ExecuteTrigger](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.ExecuteTrigger.html) controller lets you handle execute triggers, as shown in the following example:
>  
> [.highlight]
> ```typescript
const engine = searchInterface.engine!;
const availableFunctions: Record<string, Function> = {
    deprecatedProduct() { <1>
        const currentQuery = engine.state.search.queryExecuted;
        alert("The '" + currentQuery + "' product has been deprecated.");
    }
};
const executeController = buildExecuteTrigger(engine); <2>
executeController.subscribe(() => {
for (const execution of executeController.state.executions) { <3>
    const functionToExecute = availableFunctions[execution.functionName]; <4>
    if (!functionToExecute) {
        console.error(`Index tried to execute function ${functionToExecute} with parameters ${JSON.stringify(execution.params)} but it was unavailable.`);
        return;
    }
    functionToExecute(...execution.params);
}
});
```
> <1> The `deprecatedProduct()` function is defined within `availableFunctions`.
> For this particular method, any user-defined functions intended to be used with execution triggers are to be defined within `availableFunctions`.
> <2> [`buildExecuteTrigger`](https://docs.coveo.com/en/headless/latest/reference/functions/Search.buildExecuteTrigger.html) creates a controller for the execute trigger.
> <3> The `executions` property is read and iterated over from the controller state.
> It stores the function names to be executed and their respective parameters.
> <4> Each of the functions in the `executions` array is executed, or if a function isn't defined, it will display an error.
> 
> * If you're using the [Coveo Atomic library](https://docs.coveo.com/en/lcdf0264/), you must handle execute triggers by [accessing Headless through Atomic](https://docs.coveo.com/en/atomic/latest/usage/headless-through-atomic/).
> 
> * If you're using the [JSUI](https://docs.coveo.com/en/187/) library, use the [`CoveoTriggers`](https://coveo.github.io/search-ui/components/triggers.html) component to implement execute triggers.

### Redirect

Use the **Redirect** trigger rule when you want to automatically send users to a specific URL based on certain [queries](https://docs.coveo.com/en/231/).
This method is useful when displaying search results on the current search interface doesn't provide value to the user and a separate page better addresses their needs.
Common use cases include directing users to store locators, contact pages, or even external resources that fully answer the user's request.

**Example**

You manage a retail website and notice that users frequently search for `find stores` when they want to find physical store addresses.
You create a **Redirect** trigger rule that automatically redirects users to your `Store Finder` page whenever they perform a query for `find stores`.

> **Notes**
>
> Handling redirect triggers varies depending on the framework you're using:
> 
> * [Coveo Atomic library](https://docs.coveo.com/en/lcdf0264/):
> 
> ** Redirect triggers won't run using a [hosted search page](https://docs.coveo.com/en/2866/) alone.
> You can implement them when you have an [Atomic standalone search box](https://docs.coveo.com/en/atomic/latest/usage/ssb/).
> 
> ** Otherwise, you must [access Headless through Atomic](https://docs.coveo.com/en/atomic/latest/usage/headless-through-atomic/).
> 
> ** Redirection triggers are handled within the [Coveo Headless library](https://docs.coveo.com/en/lcdf0493/) using the [RedirectionTrigger](https://docs.coveo.com/en/headless/latest/reference/interfaces/Search.RedirectionTrigger.html) controller.
>  
> [.highlight]
> ```javascript
const engine = searchInterface.engine!;
const redirectController = buildRedirectionTrigger(engine);
redirectController.subscribe(() => {
    const { redirectTo } = redirectController.state;
    if (redirectTo) {
        window.location.replace(redirectTo);
    }
});
```
> 
> * [JSUI](https://docs.coveo.com/en/187/) library:
> 
> ** Use the [`CoveoTriggers`](https://coveo.github.io/search-ui/components/triggers.html) component.

## QPL syntax

Use the following [query pipeline language (QPL)](https://docs.coveo.com/en/235/) syntax to define a trigger rule:

```text
execute <function> | notify <message> | query <expression> | redirect <url>
```

### `<function>`

A string that contains the JavaScript function call to execute (for example, `myFunction()`).
Boolean, integer, and quoted string function arguments are allowed.

> **Note**
>
> When specifying a function containing arguments (for example, `myFunction(true, 123, "abc")`), the arguments aren't executed in the function as is.
> The argument values are rather returned in an object as follows:
> 
> [.highlight]
> ```javascript
{
  element: div.CoveoTriggers,
  param1: true,
  param2: 123,
  param3: "abc"
}
```
> 
> Therefore, the corresponding function must be implemented accordingly on client-side.
> For example, if the trigger expression is `execute myFunction(true,123,"abc")`, the corresponding function could be configured as follows:
> 
> [.highlight]
> ```javascript
function myFunction(paramValues) {
    /*
    `paramValues` appear in an object:
      {
         element: div.CoveoTriggers,
         param1: true,
         param2: 123,
         param3: "abc"
      }
    */
    alert("Hi, This is your answer:  " + paramValues.param3); // paramValues.param3 is "abc"
};
```

### `<message>`

A quoted string that contains a message to display to the end user (for example, `"Hello world!"`).

### `<expression>`

A query expression to perform against the [index](https://docs.coveo.com/en/204/) (for example, `coveo OR "machine learning"`).

### `<url>`

A quoted string that contains a URL to which the browser is redirected (for example, `+"http://www.example.com"+`).

## Order of execution

The following diagram illustrates the [order of execution of query pipeline features](https://docs.coveo.com/en/1376/):


![Diagram showing order of execution | Coveo](https://docs.coveo.com/en/assets/images/tune-relevance/order-of-execution-query-pipeline-features.png)

## Required privileges

The following table indicates the [privileges](https://docs.coveo.com/en/1791#required-privileges) required to view or edit trigger rules.
Learn more about the [Privilege reference](https://docs.coveo.com/en/1707/) or how to [manage privileges](https://docs.coveo.com/en/3151/).

[cols="3",options="header"]
|===
|Action
|Service - Domain
|Required access level

|View trigger rules
|Organization - Organization  
Search - Query pipelines
|View

.2+|Edit trigger rules
|Organization - Organization
|View

|Search - Query pipelines
|Edit
|===