Workflow System
The Workflow System is the core orchestration mechanism in the AVA SDK, enabling developers to create, manage, and execute automated sequences of operations.
The Workflow System is the core orchestration mechanism in the AVA SDK, enabling developers to create, manage, and execute automated sequences of operations. This document covers the architecture of the workflow system, its components, and how to interact with it programmatically.
For information about specific trigger types that initiate workflows, see Triggers. For details on the different types of nodes that can be included in workflows, see Nodes.
1. Workflow System Overview#
The Workflow System allows developers to define automated processes as a directed graph of operations (nodes) connected by relationships (edges). Workflows are triggered by specific conditions and executed by the AVS service, with execution results being recorded for monitoring and debugging.
Sources:
2. Core Components#
2.1. Workflow Structure#
A workflow is defined by the following components:
Sources:
2.2. Key Properties#
| Property | Description |
|---|---|
id | Unique identifier for the workflow, generated when submitted |
name | Human-readable name for the workflow |
smartWalletAddress | Address of the smart wallet associated with the workflow |
owner | Address of the EOA that owns the workflow |
startAt | Timestamp when the workflow should start (Unix timestamp) |
expiredAt | Timestamp when the workflow should expire (Unix timestamp) |
maxExecution | Maximum number of times the workflow can execute (0 for unlimited) |
status | Current status of the workflow (Active, Canceled, Expired) |
trigger | Condition that initiates the workflow |
nodes | Array of operations to be performed |
edges | Array of connections between nodes, defining the workflow graph |
Sources:
3. Workflow Lifecycle#
The workflow lifecycle consists of creation, submission, execution, and optional cancellation or deletion.
Sources:
3.1. Creating and Submitting Workflows#
Workflows are created in two steps:
- Create a workflow object with
client.createWorkflow() - Submit the workflow to the AVS service with
client.submitWorkflow()
Sources:
Example: Creating and Submitting a Workflow#
Sources:
3.2. Retrieving Workflows#
You can retrieve individual workflows by ID or multiple workflows by smart wallet address.
Sources:
3.3. Canceling and Deleting Workflows#
Workflows can be canceled to stop them from executing and deleted to remove them entirely.
Sources:
4. Workflow Execution#
When a workflow's trigger conditions are met, the workflow is executed by the AVS service.
Sources:
4.1. Retrieving Executions#
Execution records contain information about the execution of the workflow, including the status of each step and any outputs or errors.
Sources:
4.2. Manual Workflow Triggering#
Workflows can also be triggered manually using the triggerWorkflow method.
Sources:
5. Node Types and Configuration#
Nodes are the building blocks of workflows, representing operations that can be performed as part of a workflow. The SDK provides various node types for different operations.
Sources:
Example node configurations can be found throughout the code, including:
- Contract Read Node: examples/example.ts305-324
- REST API Node: examples/example.ts326-341
- Branch Node: tests/createWorkflow.test.ts164-191
- Filter Node: tests/createWorkflow.test.ts383-384
6. Trigger Types and Configuration#
Triggers define when workflows should be executed. The SDK supports several types of triggers.
Sources:
Example trigger configurations:
- Block Trigger: examples/example.ts277-286 tests/createWorkflow.test.ts74-79
- Cron Trigger: examples/example.ts286-296 tests/createWorkflow.test.ts109-114
- Fixed Time Trigger: tests/createWorkflow.test.ts138-142
- Event Trigger: tests/createWorkflow.test.ts220-232 tests/createWorkflow.test.ts273-290
7. Error Handling#
The Workflow System provides error handling both at the workflow level and for individual nodes.
Sources:
When retrieving executions, each step in the execution contains a success flag and potentially an error message:
8. Practical Examples#
The examples directory contains several practical workflow examples:
- Price Reporting Workflow: Fetches price data from a contract and sends it to a webhook (examples/example.ts262-368)
- Telegram Notification Workflow: Sends periodic messages to a Telegram channel (examples/example.ts371-439)
- Token Transfer Monitoring Workflow: Monitors ERC-20 transfers to a wallet and sends notifications (examples/example.ts568-670)
- Token Sweeping Workflow: Automatically transfers tokens from a wallet when deposits are received (examples/example.ts446-565)
These examples demonstrate how to construct workflows for various use cases, including blockchain monitoring, notifications, and automated token management.
9. Best Practices#
When working with the Workflow System, consider the following best practices:
- Unique IDs: Use a reliable method to generate unique IDs for triggers, nodes, and edges, such as ULIDs or UUIDs.
- Error Handling: Add appropriate error handling to your workflow nodes, especially for external API calls.
- Testing: Test your workflows thoroughly with small, controlled executions before setting them up for long-term use.
- Monitoring: Regularly monitor your workflow executions to ensure they're working as expected.
- Resource Management: Be mindful of the execution frequency and resource usage of your workflows.
10. Related Resources#
For more information about specific aspects of the Workflow System, see:
- Triggers: Details on trigger types and configuration
- Nodes: In-depth documentation of node types and their configurations
- Executions: Information about execution records and monitoring
- Smart Wallets: How smart wallets are used in workflows
- Client Interface: Documentation of the client interface for managing workflows