Triggers

Last updated
Save as PDF

Triggers work in conjunction with aggregations to monitor workflow tasks and alert you of adverse behavior or performance.

A workflow can have multiple triggers. Each trigger monitors a number of the workflow's aggregations, verifying the aggregation values every minute.

When an aggregation value meets a specified condition, the trigger sends a workflowstatus document through a trigger pipeline. A trigger pipeline can contain any stages you want, but should ideally include stages that can notify you that the trigger condition was met, for example the Email Notification stage.

For more information about aggregations, see Aggregations

For an example scenario of how you can use triggers and aggregations together, see Using aggregations and triggers to monitor a workflow.

Trigger expressions

Each trigger contains an expression that determines when the trigger is started.

These expressions are built from a number of rules. Rules can be grouped together using AND and OR operators. Each rule contains these elements:

Aggregation name: The name of an aggregation to monitor.
TipSpecify Workflow Metrics to monitor certain properties of the workflow itself. For more information, see Workflow metrics information for triggers.
Key: A specific piece of data to monitor for the selected aggregation
For example, if you select a Document Field Aggregate aggregation, you specify the name of a document field.
Some aggregations, such as Long Sum Aggregate, do not need a key specified.
Trigger value: A value against which to compare an aggregation value. Some comparators, such as is_empty or field_exists, do not need a value specified.
Comparator: The method by which the system should compare the value you specify against the value in an aggregation.

List of trigger comparators

Comparator	Negative version	Description
equals	not_equal	Verifies whether the value you specify exactly matches the corresponding aggregation value.
less_than	N/A	Verifies whether the value you specify is less than the corresponding aggregation value.
less_or_equals	N/A	Verifies whether the value you specify is less than or equal to the corresponding aggregation value.
greater_than	N/A	Verifies whether the value you specify is greater than the corresponding aggregation value.
greater_or_equals	N/A	Verifies whether the value you specify is greater than or equal to the corresponding aggregation value.
contains	not_contains	Verifies whether the aggregation value contains the value you specify.
field_exists	field_does_not_exist	Verifies whether the key you specified exists for the aggregation.
is_empty	is_not_empty	Verifies whether the key you specified is empty.

Example trigger expression

In this example expression, the trigger fires when the workflow has processed exactly 100 PDF documents.

Aggregation	Key	Comparator	Value
MIME Types	application/pdf	equals	100

Here, the trigger monitors the default MIME Types aggregation to track the number of processed documents that have the MIME type application/pdf.

For information on the MIME Types aggregation, see Default aggregations.

Trigger pipelines

A trigger pipeline is similar to a workflow pipeline in that it contains multiple processing pipelines that execute one after another.

While a workflow pipeline processes all documents read from a workflow's data sources and executes when a workflow task runs, trigger pipelines:

Execute only when a trigger condition is met.
Process only a special workflow status document. Trigger pipelines do not process documents read from data sources.

TipUse the Email Notification stage or Syslog Notification stage in your trigger pipelines.

Trigger pipeline documents

When a trigger condition is met, a special document is sent through the trigger pipeline. This document contains:

Workflow metrics information fields. See Workflow metrics information for triggers.
Fields containing the names and values of each workflow aggregation.

NoteIf an aggregation name contains spaces, the spaces are replaced with underscores in the trigger pipeline document.

Example trigger pipeline document

This example trigger pipeline document contains Workflow Metrics information and fields for aggregations named maxTemp and Extensions.

{
// note - begin workflow metrics fields
"bytes_read":"0",
"deletes_performed":"0",
"delete_requests":"0",
"dropped":"0",
"duration":"0",
"expanded":"0",
"failures":"0",
"input":"0",
"output":"0",
"runtime":"0",
"updates_performed":"0",
"update_requests":"0",
"bytesAverage":{
"resultType":"LONG",
"values":[
"10"
]
},
// note - begin fields for other aggregations
"maxTemp":{
"resultType":"LONG",
"values":[
"50"
]
},
"Extensions":{
"resultType":"STRING_TO_LONG_PAIRS",
"values":[
" { \"key\" : \".json\", \"value\": \"1\"} ",
" { \"key\" : \".xml\", \"value\": \"2\"} ",
" { \"key\" : \".docx\", \"value\": \"3\"} "
]
}
}

Adding triggers to a workflow

Before you begin

Before adding a trigger to a workflow, you need to:

Create the workflow aggregations that you want the trigger to monitor.
Create the pipelines you want the trigger to use.

Procedure

Click the Workflow Designer window.
Select the workflow that you want.
Click the Task window.
Click the Triggers window.
Click the Add Trigger + tab.
Name the trigger, and, optionally, write a description for it.
Specify an expression:
1. Click Add Condition.
2. Configure the condition:
  - In the Aggregation field, type the name of one of the workflow's aggregations.
    TipThe available aggregations for the workflow are displayed in the Aggregations box.
  - Conditionally, type or select a value for the Key field.
  For example, if you selected the default Discovered Fields aggregation, specify the name of a field, such as HCI_size.
  TipIf you selected the Workflow Metrics aggregation, the available keys are displayed in the Aggregations box.
  - From the menu, select a comparator. For information on the available comparators, see List of trigger comparators.
  - Depending on the comparator you selected, specify a value to be compared against the aggregation value.
3. Optionally, add another condition or group.
4. For each group of conditions, select a logical operator: either AND or OR.
Set up the trigger pipeline:
1. Click the Add Pipeline + tab.
2. On the add Pipeline to Trigger page, select a pipeline. Then click Add to Trigger.
3. Repeat the previous steps for each pipeline you want to add to the trigger.
Click Add Trigger to add it to your workflow.

Example trigger pipeline

In this example, a workflow called tempMonitor contains an aggregation called averageTemperature and a trigger called tempExceeded. The trigger is activated when the aggregation value exceeds 100.

When the trigger condition is met, the trigger sends a workflow status document through this example trigger pipeline, which contains a single Email Notification stage. The Email Notification stage sends an email notification that contains the current value for the averageTemperature aggregation.

Workflow metrics information for triggers

Each workflow has a special aggregation named Workflow Metrics that lets a workflow's triggers monitor certain properties of the workflow itself. When a trigger's conditions are met, the Workflow Metrics properties are added as document fields to the special documents that are sent through trigger pipelines.

Workflow Metric	Document Field Name	Description
Bytes Read	bytes_read	The total number of bytes read by the workflow task.
Deletes Performed	deletes_performed	The number of documents exiting the workflow pipeline that include the HCI_operation:DELETED field/value pair.
Delete Requests	delete_requests	The number of documents entering the workflow pipeline that include the HCI_operation:DELETED field/value pair.
Dropped	dropped	Dropped: Typically, the number of documents removed from the pipeline by a Drop Documents stage. This metric is also incremented if any of your own custom stages exhibit this behavior; when a document enters the stage, it produces zero output documents and zero errors.
Duration	duration	The total amount of computing time spent processing the task, across all instances.
Expanded	expanded	The number of documents added due to expanding archive files. This number does not include the archive files themselves.
Failures	failures	The number of documents that failed to be processed.
Total Input	input	The number of documents that have entered the workflow pipeline.
Total Output	output	The number of documents that exited the workflow pipeline.
Runtime	runtime	The amount of real-world time since the task started running.
Updates Performed	updates_performed	The number of documents exiting the workflow pipeline that include the HCI_operation:CREATED field/value pair.
Update Requests	update_requests	The number of documents entering the workflow pipeline that include the HCI_operation:CREATED field/value pair.

Quick Links

Trigger expressions

List of trigger comparators

Example trigger expression

Trigger pipelines

Trigger pipeline documents

Example trigger pipeline document

Adding triggers to a workflow

Example trigger pipeline

Workflow metrics information for triggers