Manage trigger rules

This is for:

In this article

Prerequisites
Access the "Triggers" subtab
Add or edit trigger rules
Duplicate trigger rules
Copy trigger rules to another pipeline
Delete trigger rules
Change the rule order
When and why to use trigger rules
QPL syntax
Order of execution
Required privileges

trigger rules define an action to execute in a search interface when a query meets the associated conditions. By default, the list of query pipeline triggers for a Coveo organization 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 or redirecting the web browser to a specific URL).

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 to be able to test the rule that you create.
An existing query pipeline

The queries from the search page must travel through a specific query pipeline.
Required privileges

You need specific privileges to be able to add and edit rules in a query pipeline.

Once you meet these requirements, you can create a rule on the Query Pipelines (platform-ca | platform-eu | platform-au) page. To test the rule, use the A/B test feature 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 of the query pipeline you want to manage.

On the Query Pipelines (platform-ca | platform-eu | platform-au) 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 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.
When adding a trigger to a list of existing rules, you can also click , 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.

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, in the String box, enter a message to display in the search interface.
- For Query, in the Query box, enter a query to perform as a new search in the search interface.
- For Execute, in the Function box, enter a JavaScript function to execute in the user’s browser.
- For Redirect, in the URL box, enter a URL to redirect the user.
Under Condition, select a query pipeline condition in the dropdown menu or create a new one.

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 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 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 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.

To avoid undesired search behaviors, delete unused query pipeline rules, as they can impact search relevance.
Consider using the Groups & Campaigns feature 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 (platform-ca | platform-eu | platform-au) 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 Advanced tab.
In the Advanced tab, on the left side of the page, select Triggers.
In the Triggers 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 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
Query
Execute
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, use the atomic-notifications 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.
If you’re using the Coveo Headless library, use the NotifyTrigger 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.

The approach to capture notification link clicks differs depending on whether the links redirect to items in your index or external resources (that is, resources that aren’t in your index):

When notification links redirect to items in the index, log these clicks as regular click events.

These clicks are taken into account in the Search Event Clickthrough metric and Coveo Machine Learning (Coveo ML) Automatic Relevance Tuning (ART) models can learn from them.

When notification links redirect to external resources, the best approach is to log these clicks as custom events.

Since the resources aren’t in your index, you don’t have all the information necessary to send the 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 rate related to these clicks, use report cards. The default Search Event Clickthrough metric 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 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 dividing the click count by the query count multiplied by 100.

clickthrough usage analytics metric cards

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 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, the atomic-did-you-mean component is used to display changes made to the user’s query by a query trigger.
If you’re using the Coveo Headless library, use the QueryTrigger 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

Notes

The Coveo Headless library ExecuteTrigger controller lets you handle execute triggers, as shown in the following example:

const engine = searchInterface.engine!;
const availableFunctions: Record<string, Function> = {
    deprecatedProduct() { 
        const currentQuery = engine.state.search.queryExecuted;
        alert("The '" + currentQuery + "' product has been deprecated.");
    }
};
const executeController = buildExecuteTrigger(engine); 
executeController.subscribe(() => {
for (const execution of executeController.state.executions) { 
    const functionToExecute = availableFunctions[execution.functionName]; 
    if (!functionToExecute) {
        console.error(`Index tried to execute function ${functionToExecute} with parameters ${JSON.stringify(execution.params)} but it was unavailable.`);
        return;
    }
    functionToExecute(...execution.params);
}
});

	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`.
	`buildExecuteTrigger` creates a controller for the execute trigger.
	The `executions` property is read and iterated over from the controller state. It stores the function names to be executed and their respective parameters.
	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, you must handle execute triggers by accessing Headless through Atomic.
If you’re using the JSUI library, use the CoveoTriggers 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. 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:

Redirect triggers won’t run using a hosted search page alone. You can implement them when you have an Atomic standalone search box.
Otherwise, you must access Headless through Atomic.

Redirection triggers are handled within the Coveo Headless library using the RedirectionTrigger controller.

const engine = searchInterface.engine!;
const redirectController = buildRedirectionTrigger(engine);
redirectController.subscribe(() => {
    const { redirectTo } = redirectController.state;
    if (redirectTo) {
        window.location.replace(redirectTo);
    }
});

JSUI library:
- Use the CoveoTriggers component.

QPL syntax

Use the following query pipeline language (QPL) syntax to define a trigger rule:

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:

{
  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:

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 (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:

Required privileges

The following table indicates the privileges required to view or edit trigger rules. Learn more about the Privilege reference or how to manage privileges.

Action	Service - Domain	Required access level
View trigger rules	Organization - Organization Search - Query pipelines	View
Edit trigger rules	Organization - Organization	View
Search - Query pipelines	Edit

Action

Service - Domain

Required access level

View trigger rules

Organization - Organization
Search - Query pipelines

View

Edit trigger rules

Organization - Organization

View

Search - Query pipelines

Edit