Manage trigger rules

This is for:

Developer System Administrator

Members with the required privileges can use query pipeline triggers to define an action to execute in a search interface when a query meets the associated condition.

The list of query pipeline triggers for a Coveo organization is empty by default.

When a trigger rule is applied, 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, notifying the end user with a corresponding message, etc.).

Prerequisites

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

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.

Create trigger rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to add a rule, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the upper-right corner of the page, click Add Rule to access the Add a Trigger Rule [1] subpage.

  5. Under Type, select one of the available methods (Notify, Query, Execute, or Redirect).

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

  7. On the right side, under Condition, select a query pipeline condition in the dropdown menu or create a new one.

    Important

    If a trigger rule isn’t associated with a query pipeline condition, the rule is ignored.

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

  9. Click Add rule.

Edit trigger rules

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline in which you want to edit a rule, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. Click the rule you want to edit, and then click Edit in the Action bar [2] to access the Edit a Trigger Rule subpage.

  5. Under Type, select one of the available methods (Notify, Query, Execute, or Redirect).

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

  7. On the right side, under Condition, select a query pipeline condition in the dropdown menu or create a new one.

    Important

    If a trigger rule isn’t associated with a query pipeline condition, the rule is ignored.

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

  9. Click Save.

Duplicate trigger rules

You can duplicate trigger rules within the same pipeline.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to duplicate rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the Triggers subtab, select each checkbox next to the rules you want to duplicate within the same pipeline.

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

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline from which you want to copy rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the Triggers subtab, select each checkbox next to the rules you want to copy to another pipeline.

  5. In the Action bar, click More, and then click Copy to…​.

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

Review information about the rule’s creation or last modification

You can verify who created or last modified a given trigger rule by inspecting the Details column of the Triggers subtab. The Details column also indicates the hour and date the rule was created or last modified.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline containing the rule for which you want to inspect the information of the Details column, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the Triggers subtab, inspect the information of the Details column for the desired rule.

Delete trigger rules

You can delete trigger rules from a query pipeline.

  1. On the Query Pipelines (platform-ca | platform-eu | platform-au) page, click the query pipeline for which you want to delete rules, and then click Edit components in the Action bar.

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the Triggers subtab, select each checkbox next to the rules you want to delete.

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

  6. Click Delete to confirm.

Change the rule order

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

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

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

  3. In the Advanced tab, on the left side of the page, select Triggers.

  4. In the Triggers subtab, click the rule whose position you want to change.

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

Reference

Methods

When managing trigger rules, you can select one of the following trigger types:

Notify

When creating or editing a Notify trigger rule, in the String box, enter a message to display in the search interface.

Example

On your internal search page for parts, each time a query is performed without a model number, you want to show Add a model number to your query to the user.

You use the Coveo Atomic library atomic-notifications component to handle notifications generated by the notify triggers.

Notify trigger being displayed in a search page using atomic-notification component
Notes
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 usage analytics reports.

The approach to capture clicks notification links differs depending on whether the links redirects 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.

    • If you want to calculate the clickthrough rate related to these clicks, you must 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 clicks the notification link (click count), and one calculated metric card dividing the click count by the query count multiplied by 100.

      clickthrough usage analytics metric cards
    Tip
    Leading practice

    Considering these facts, we recommend that you 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

When creating or editing a Query trigger rule, in the Query box, enter a query to perform as a new search in the search interface.

Example

For the Coveo Atomic library, the atomic-did-you-mean component can be used to display any changes brought to the query by a query trigger.

Query trigger change being displayed in a search page using atomic-did-you-mean component
Notes

  • If you’re using the Coveo Headless library, the QueryTrigger controller lets you implement query triggers.

  • If you’re using the JSUI library, the CoveoTriggers component lets you implement query triggers.

Execute

When creating or editing an Execute trigger rule, in the Function box, enter a JavaScript function to execute in the user’s browser.

Example

  • Suppose you recently deprecated the ACME CTRLR product, but realize that your support agents still search for it. To make sure that all your agents are aware of that recent change, you configured the deprecatedProduct() function in your search interface to alert them when they’re about to send the ACME ctrlr query.

  • Since you want this function to execute only when the ACME ctrlr query is sent, you configure an Execute trigger rule that targets the deprecatedProduct() function and that executes only when a user sends the ACME ctrlr query.

    execute trigger rule in the Administration Console

  • 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() { 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 function intended to be used with execution triggers are to be defined within availableFunctions.
    2 buildExecuteTrigger 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 function in the executions array is executed or a corresponding error is displayed if the function requested isn’t defined.
Notes

  • If you’re using the Coveo Atomic library, see Access Headless through Atomic because execute triggers must be handled with Headless.

  • If you’re using the JSUI library, the CoveoTriggers component lets you implement execute triggers.

Redirect

When creating or editing a Redirect trigger rule, in the URL box, enter a URL to redirect the user.

Example

For certain queries, you always want a specific web page to be opened. A user searching find stores is automatically redirected to your Store Finder page instead of being shown search results that contain the phrase find stores.

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);
    }
});
Notes

If you’re using the Coveo Atomic library:

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 overall order of execution of query pipeline features:

diagram showing order of execution

Required privileges

By default, members with the required privileges can view and edit elements of the Query Pipelines (platform-ca | platform-eu | platform-au) page.

The following table indicates the required privileges for members to view or edit trigger rules (see Manage privileges and Privilege reference).

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
1. (Advanced) You can click Menu, and then select Add rule with code to define the rule using the appropriate QPL syntax.
2. (Advanced) You can click More, and then select Edit code to edit the rule using the appropriate QPL syntax.