Trigger Actions
Comparable to: RPC vs message queue vs fire-and-forget patterns
Key Concepts
Use the concepts below when they fit the task. Not every invocation needs all three modes.
- Synchronous (default): caller blocks until the function returns a result or times out
- Void (
TriggerAction.Void()): fire-and-forget dispatch, returns immediately withnull, no retry guarantees - Enqueue (
TriggerAction.Enqueue({queue})): routes through a named queue with automatic retries and backoff, returns amessageReceiptId - Decision guide: need the result? use sync. Must complete reliably? use enqueue. Optional side effect? use void.
Architecture
The caller invokes trigger() with an optional action parameter. Synchronous mode waits for the handler result. Void mode dispatches and returns null immediately. Enqueue mode places the payload on a named queue where a consumer processes it with retry guarantees.
iii Primitives Used
| Primitive | Purpose |
|---|---|
trigger({function_id, payload}) | Synchronous invocation, blocks for result |
trigger({..., action: TriggerAction.Void()}) | Fire-and-forget, returns immediately with null |
trigger({..., action: TriggerAction.Enqueue({queue})}) | Durable async via named queue, returns receipt |
iii trigger --function-id=ID --payload=JSON | CLI trigger (part of the engine binary) |
--timeout-ms | CLI flag to set trigger timeout (default 30s) |
Reference Implementation
See ../references/trigger-actions.js for the full working example — a comparison of all three
Also available in Python: ../references/trigger-actions.py
Also available in Rust: ../references/trigger-actions.rs invocation modes showing when and how to use sync, void, and enqueue patterns.
Common Patterns
Code using this pattern commonly includes, when relevant:
await iii.trigger({function_id: 'users::get', payload: {id}})— sync, get result directlyiii.trigger({function_id: 'analytics::track', payload: event, action: TriggerAction.Void()})— fire-and-forgetiii.trigger({function_id: 'orders::process', payload: order, action: TriggerAction.Enqueue({queue: 'payments'})})— durable enqueue- Sync returns the function result directly
- Void returns
null/None - Enqueue returns
{messageReceiptId: string}for tracking iii trigger --function-id='users::get' --payload='{"id":"123"}'— invoke via CLIiii trigger --function-id='users::get' --payload='{"id":"123"}' --timeout-ms=5000— with custom timeout
Adapting This Pattern
Use the adaptations below when they apply to the task.
- Default to synchronous when the caller needs the result to proceed
- Use void for logging, analytics, or any side effect where failure is acceptable
- Use enqueue for anything that must complete reliably — payments, emails, notifications
- Combine modes in a single handler: sync call for validation, then enqueue for processing
- Named queues let you configure retries and concurrency per workload type
Pattern Boundaries
- For queue configuration (retries, concurrency, FIFO ordering), prefer
iii-engine-config. - For DLQ handling when enqueued jobs exhaust retries, prefer
iii-dead-letter-queues. - For function registration and trigger binding, prefer
iii-functions-and-triggers. - Stay with
iii-trigger-actionswhen the primary problem is choosing the right invocation mode.
When to Use
- Use this skill when the task is primarily about
iii-trigger-actionsin the iii engine. - Triggers when the request directly asks for this pattern or an equivalent implementation.
Boundaries
- Never use this skill as a generic fallback for unrelated tasks.
- You must not apply this skill when a more specific iii skill is a better fit.
- Always verify environment and safety constraints before applying examples from this skill.