Triggers

Overview

Triggers determine when Answer Generators should be activated, based on the results of content recognition. Triggers specify which Content Recognizers should run and which Semantic Data Collections should be searched, then examine the output of all recognition to determine whether or not to activate.

Triggers only signal whether or not activation should occur, not which Answer Generators to activate. (Answer Generator - Trigger Associations use the result of a Trigger to activate a specific Answer Generator.)

Special Triggers

There are two special Triggers that you can use to activate your Answer Generators: the Any Trigger and the Always Trigger.

The Any Trigger

The Any Trigger activates an Answer Generator unless it is part of an Engine that the user has chosen to be active by default, and the Engine isn't explicitly activated. This is suitable for Answer Generators in domain-specific Engines that are active by default, so that normal searches don't activate the Answer Generator. But if the Engine is activated by activation codes, keywords, or the search options panel, the Answer Generator will be triggered.

For example, an Answer Generator that outputs a link to the search page of a deals site might be added to a "Deals" Engine, triggering on the Any Trigger. The user makes the "Deals" Engine active by default, but normal searches won't contain the link to the search page of the deals site. If the user explicitly activates the "Deals" Engine, the Answer Generator will run and a link to the deals site will appear in the answer page.

The Always Trigger

The Always Trigger activates an Answer Generator unconditionally. This is useful for activating Answer Generators that do a general purpose search, like the Google Search Answer Generator. An Answer Generator activated by the Always Trigger will always be run, regardless if the containing Engine was explicitly activated.

How Triggers Work

Now let's talk about how to create your own Triggers. First, let's learn how they work.

Input

The following information is available to Triggers:

Name Example Value Description
q 92126 The user's answer query, with activation codes and options (like --debug) removed, truncated to 80 characters, and trimmed of leading and trailing whitespace
recognitionResults
{
  "com.solveforall.recognition.Number" : [
    {
      "matchedText" : "92126",
      "recognitionLevel" : 0.5,
      "number" : "92126"
    }
  ],
  "com.solveforall.recognition.location.UsAddress" : [
    {
      "matchedText" : "San Diego",
      "recognitionLevel" : 1.0,
      "city" : "San Diego",
      "state" : "California",
      "stateAbbreviation" : "CA",
      "zipCode" : "92126"
    }
  ]
}
See Combined Content Recognition Results.
context { "user" : { ... }, "pageUri" : "http://blah.com", "location" : { ... }, ... } See Query Context

Output

Triggers output a Boolean value indicating whether or not activation should occur.

Common Trigger Properties

In addition to the common plugin properties, all Triggers have the following additional properties:

Name Example Value Description
Content Recognizers United States Address, Geo Coordinates A set of Content Recognizers that the Trigger depends on. These Content Recognizers will always be run if the user has selected to add an Answer Generator - Trigger Association referencing the Trigger.
Semantic Data Collections HTML Elements, CSS Properties A set of Semantic Data Collections that the Trigger depends on. These Semantic Data Collections will always be searched if the user has selected to add an Answer Generator - Trigger Association referencing the Trigger.

Kinds of Triggers

Developers can create Triggers implemented in one of three ways:

Either kind of Trigger can be created on the Trigger creation form.

Simple Triggers

Simple Triggers work by requiring the presence of at least one member of a set of recognition keys. If none of the recognition keys appears in the recognition results, the Trigger does not activate. For any recognition key that does appear, a Simple Trigger activates if there is a recognition result mapped to the key that has a recognition level greater than or equal to the minimum recognition level of the Simple Trigger.

In addition to the common trigger properties, Simple Triggers have the following properties:

Name Example Value Description
Recognition Keys com.solveforall.recognition.location.UsAddress The recognition key(s) to look for. To specify multiple keys, separate the keys with commas.
Minimum Recognition Level 0.75 If zero, as long as the recognition key appears in the recognition results, the Trigger will activate. Otherwise, the Trigger looks for a recognition result mapped to the recognition key that has a recognition level at least the minimum recognition level. The Trigger will activate only if such a result is found.

Given the combined recognition result:

{
  "com.solveforall.recognition.location.UsAddress" : [
    {
      "matchedText" : "92126-6221",
      "recogitionLevel" : 0.8,
      ...
    }
  ]
}

a Simple Trigger configured as above would output true (since 0.8 >= 0.75), indicating that the Trigger is activated. If the recognition level were replaced with 0.6, the same Trigger would output false, since 0.6 < 0.75.

Simple Triggers are by far the most common type of Triggers. Most of the time when a new Content Recognizer is created, a Simple Trigger using only the new Content Recognizer is also created.

External Javascript Triggers

If you know how to program in Javascript, you can create Triggers by writing Javascript. See Javascript Execution for information about the execution environment.

To create an External Javascript-backed Content Trigger, you first decide which Content Recognizers you need to run. Then just create a file, say trigger.js that implements the following function:

function shouldActivate(q, recognitionResults, context) {
  if (...) {
    return true; // Activate
  }
  return false; // Do not activate
}

in the top level scope, where recognitionResults is an Object containing the Combined Content Recognition Results. The function should return true if the trigger should activate; otherwise it should return false.

Note! If activation is desired, shouldActivate() should return true, not just any truthy value (strings, numbers, etc. won't be converted to a Boolean value and will be treated as false).

For example, here's an implementation that looks for either UPS or Fedex tracking numbers and activates if any recognition level was greater than or equal to 0.5:

function shouldActivate(q, recognitionResults, context) {
  const upsResults = recognitionResults['com.solveforall.recognition.business.UPSTrackingNumber'] || [];
  const fedexResults = recognitionResults['com.solveforall.recognition.business.FedexTrackingNumber'] || [];
  const allResults = upsResults.concat(fedexResults);

  for (let i = 0; i < allResults.length; i++) {
    const result = allResults[i];
    if (result.recognitionLevel >= 0.5) {
      return true;
    }
  }
  return false;
}

Once you have written this file, follow these steps to publish your External Javascript Trigger:

  • Go to the Trigger creation form
  • Select a Type of "External Javascript"
  • Fill in the common Plugin properties
  • Choose the Content Recognizers to run
  • Choose the Semantic Data Collections to search
  • Attach the trigger.js file you just created
  • Save the Trigger

Inline Javascript Triggers

If your Trigger logic is short and sweet, you may choose to send the Javascript expression for the Trigger instead of an entire file. The expression will be evaluated as follows:

function (q, rr, c) {
  return /*Your Inline Javascript Here!*/;
}
where rr is the Combined Content Recognition Results, and c is the Query Context.

For example, this expression ensures that both a city and state were found by a Content Recognizer outputting results with the recognition key com.solveforall.recognition.UsAddress:

(rr['com.solveforall.recognition.UsAddress'].city.length > 0) &&
(rr['com.solveforall.recognition.UsAddress'].state.length > 0)
Note that if an error occurs executing the Javascript, the Trigger will be considered as not activated. This is desired in the case in where the com.solveforall.recognition.UsAddress recognition key was not present in the results, which causes the evaluation of rr['com.solveforall.recognition.UsAddress'].city.length to result in an error.

Once you have crafted your expression, follow these steps to publish your Inline Javascript Trigger:

  • Go to the Trigger creation form
  • Select a Type of "Inline Javascript"
  • Fill in the common Plugin properties
  • Choose the Content Recognizers to run
  • Choose the Semantic Data Collections to search
  • Fill in the "Filter Expression" with your expression
  • Save the Trigger

Next Steps

Triggers activate Answer Generators which are probably what you are looking for next.