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 with

  null

  , no retry guarantees
• Enqueue (

  TriggerAction.Enqueue({ queue })

  ): routes through a named queue with automatic retries and backoff, returns a

  messageReceiptId

• Decision guide: need the result? use sync. Must complete reliably? use enqueue. Optional side effect? use void.

Architecture

The caller invokes

trigger()

iii Primitives Used

trigger({ function_id, payload })

trigger({ ..., action: TriggerAction.Void() })

trigger({ ..., action: TriggerAction.Enqueue({ queue }) })

iii trigger --function-id=ID --payload=JSON

--timeout-ms

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 directly

• iii.trigger({ function_id: 'analytics::track', payload: event, action: TriggerAction.Void() })

  — fire-and-forget

• iii.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 CLI

• iii 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-actions

  when the primary problem is choosing the right invocation mode.

When to Use

• Use this skill when the task is primarily about

  iii-trigger-actions

  in 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.