Trigger: Query pipeline feature

This is for:

In this article

Syntax
Example

A query pipeline statement expressing the trigger query pipeline feature defines an action to execute in the search interface from which a query originates.

If a statement expressing the trigger feature isn’t associated with a query pipeline condition, it’s ignored.

The following trigger actions are available:

execute executes a custom JavaScript function call.
notify displays a message to the end user.
query performs a new query.
redirect redirects the web browser to a specific URL.

When a statement expressing the trigger feature 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.).

Notes

In the Coveo Administration Console, you can manage statements expressing the trigger feature from the Triggers tab (see Manage trigger rules).
For usage in Headless/Atomic interfaces, see Manage trigger rules - Reference.
In a full Coveo JavaScript Search Framework interface, you use the Triggers component to automatically handle trigger actions. Since the March 2020 Release (v2.8521), standalone search boxes automatically handle redirect triggers without the need for a Triggers component.

The following diagram shows the process of a query being sent to the Search API and the order of execution of query pipeline features.

Syntax

Use the following query pipeline language (QPL) syntax to define a statement expressing the trigger feature:

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

Example

You create a global condition with the following QPL definition:

when $query contains "trigger statement"

In an empty query pipeline named Testing Triggers, you create three distinct statements, each expressing the trigger feature, with the following QPL definitions:

Statement 1:

execute showAnimation("triggerStatement", 100, true)

Statement 2:

notify "Here is some information about the `trigger` query pipeline feature!"

Statement 3:

query `@title=="Trigger: Query pipeline feature"`

You associate each of these statements with the global condition you created.

A user performs a query against your index with the following payload:

{
  "pipeline": "Testing Triggers",
  "q": "how do trigger statements work"
}

This query goes through the Testing Triggers query pipeline and satisfies the condition of each statement in that pipeline, so all of the statements are applied. As a result, the triggers property of the query response is populated as follows:

[
  {
    "type": "execute",
    "content": {
      "name": "showAnimation",
      "params": ["triggerStatement", 100, true]
    }
  },
  {
    "type": "notify",
    "content": "Here is some information about the `trigger` query pipeline feature!"
  },
  {
    "type": "query",
    "content": "@title==\"Trigger - Query pipeline feature\""
  }
]

The search interface from which the query originated ensures that the corresponding actions are executed.