Triggers
This page documents triggers in the Ava SDK JS, which are the mechanisms that initiate workflow executions.
This page documents triggers in the Ava SDK JS, which are the mechanisms that initiate workflow executions. Triggers define when and under what conditions a workflow should run, forming a critical part of the workflow automation system. For information about how workflows are created and structured, see Workflow System, and for details about workflow execution, see Executions.
Overview#
Triggers are the starting point of workflow automation in the Ava Protocol. Each workflow has exactly one trigger that determines when the workflow should be executed. The SDK provides several trigger types to accommodate different automation scenarios, from time-based scheduling to blockchain event monitoring.
Sources:
Trigger Types#
The Ava SDK supports five types of triggers, each designed for different automation scenarios:
| Trigger Type | Description | Use Case |
|---|---|---|
| Block | Executes a workflow at a specified block interval | Perform actions every N blocks |
| Cron | Executes a workflow according to cron schedule patterns | Run workflows on a recurring schedule |
| FixedTime | Executes a workflow at specific timestamps | Run workflows at predetermined times |
| Event | Executes a workflow when specific blockchain events occur | React to smart contract events |
| Manual | Allows workflows to be triggered manually | On-demand workflow execution |
Block Trigger#
The Block trigger executes a workflow at a specified block interval. This is useful for operations that need to be performed regularly based on blockchain progression rather than wall-clock time.
Example usage:
Sources:
Cron Trigger#
The Cron trigger executes a workflow according to cron schedule patterns. This is ideal for recurring tasks that need to run at specific times, dates, or intervals.
Example usage:
Sources:
FixedTime Trigger#
The FixedTime trigger executes a workflow at specific UNIX timestamps. This is useful for one-time executions at predetermined times.
Example usage:
Sources:
Event Trigger#
The Event trigger executes a workflow when specific blockchain events occur. This is powerful for creating reactive workflows that respond to on-chain activities.
Example usage:
The expression field uses a domain-specific language to define conditions for when the trigger should fire. In this example, it's looking for ERC-20 Transfer events (identified by the topic hash) where the recipient is the specified wallet address.
Sources:
Manual Trigger#
The Manual trigger does not automatically execute workflows but allows them to be triggered manually using the Client's triggerWorkflow method. This is useful for on-demand workflow execution.
Creating Triggers#
Triggers are created using the TriggerFactory.create() method, which takes an object with the following properties:
Where TriggerData varies depending on the trigger type as shown in the previous sections.
The TriggerType enum defines the available trigger types:
Sources:
Manual Workflow Triggering#
In addition to the automatic triggering based on the configured trigger type, the SDK allows for manually triggering a workflow using the client.triggerWorkflow() method:
Example usage:
The reason parameter must match the trigger type of the workflow and provide the necessary data for that trigger type:
| Trigger Type | Required Reason Properties |
|---|---|
| Block | blockNumber |
| Cron | epoch |
| FixedTime | epoch |
| Event | blockNumber, txHash, logIndex (optional) |
The isBlocking parameter determines whether the call will wait for the workflow execution to complete (true) or return immediately with a queued status (false).
Sources:
- tests/triggerWorkflow.test.ts87-94
- tests/triggerWorkflow.test.ts151-158
- tests/triggerWorkflow.test.ts203-210
- tests/triggerWorkflow.test.ts256-265
Trigger Execution Results#
When a workflow is triggered, either automatically or manually, it creates an execution that includes information about the trigger:
The triggerReason field indicates why the workflow was triggered, and the triggerOutput field contains data related to the trigger that can be used by nodes in the workflow.
Sources:
Workflow and Trigger Relationship#
This diagram illustrates the relationship between workflows, triggers, and executions in the Ava SDK. Each workflow has exactly one trigger that defines when it should be executed. When a trigger condition is met, it creates an execution with details about what triggered it.
Sources:
Conclusion#
Triggers are a fundamental part of the Ava workflow system, determining when and under what conditions a workflow runs. The SDK provides a variety of trigger types to support different automation scenarios, from time-based scheduling to event-driven reactions. Understanding how to properly configure and use triggers is essential for creating effective workflow automations with the Ava SDK.
For more details on creating complete workflows with nodes and edges, refer to the Workflow System documentation, and for information on how workflow executions work, see Executions.