Goal

Run a Function whenever a specific state value changes, using a state trigger.

Steps

1. Enable the State module

yaml

modules:
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based  # Options: in_memory, file_based
          file_path: ./data/state_store.db  # required for file_based

2. Register the Function

The state trigger fires whenever the watched scope/key pair changes. The handler receives an event with key, new_value, old_value, scope, and event_type properties.

<Tabs> <Tab title="Node / TypeScript"> ```typescript title="state-watcher.ts" import { registerWorker, Logger } from 'iii-sdk'

const iii = registerWorker(process.env.III_URL ?? 'ws://localhost:49134')

iii.registerFunction({ id: 'orders::on-status-change' }, async (event) => { const logger = new Logger() logger.info('Order status changed', { key: event.key, new_value: event.new_value }) // ...react to the change here... return { handled: true } })

</Tab>
<Tab title="Python">
```python title="state_watcher.py"
import os

from iii import Logger, register_worker

iii = register_worker(os.environ.get("III_URL", "ws://localhost:49134"))


def on_status_change(event):
    logger = Logger()
    logger.info("Order status changed", {"key": event["key"], "new_value": event["new_value"]})
    # ...react to the change here...
    return {"handled": True}


iii.register_function({"id": "orders::on-status-change"}, on_status_change)

</Tab> <Tab title="Rust"> ```rust title="state_watcher.rs" use iii_sdk::{register_worker, InitOptions, Logger, RegisterFunctionMessage}; use serde_json::json; use tokio::signal;

#[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let url = std::env::var("III_URL").unwrap_or_else(|_| "ws://127.0.0.1:49134".to_string()); let iii = register_worker(&url, InitOptions::default());

iii.register_function(
    RegisterFunctionMessage {
        id: "orders::on-status-change".into(),
        description: None,
        request_format: None,
        response_format: None,
        metadata: None,
        invocation: None,
    },
    |event| async move {
        let logger = Logger::new();
        logger.info("Order status changed", Some(json!({ "key": event["key"], "new_value": event["new_value"] })));
        // ...react to the change here...
        Ok(json!({ "handled": true }))
    },
);

println!("Watching orders/status for changes");
signal::ctrl_c().await?;
Ok(())

}

</Tab>
</Tabs>

### 3. Register the state trigger

Each state trigger watches a single `scope`/`key` pair. To react to multiple keys, register a function and trigger for each.

<Tabs>
<Tab title="Node / TypeScript">
```typescript title="state-trigger.ts"
iii.registerTrigger({
  type: 'state',
  function_id: 'orders::on-status-change',
  config: { scope: 'orders', key: 'status' },
})

// Then run iii.trigger() from another function or worker to trigger the state change
await iii.trigger({
  function_id: 'state::set',
  payload: {
    scope: 'orders',
    key: 'status',
    value: { orderId: 'order-123', status: 'shipped' },
  },
})

</Tab> <Tab title="Python"> ```python title="state_trigger.py" iii.register_trigger({ "type": "state", "function_id": "orders::on-status-change", "config": {"scope": "orders", "key": "status"}, })

Then run iii.trigger() from another function or worker to trigger the state change

iii.trigger({ "function_id": "state::set", "payload": { "scope": "orders", "key": "status", "value": {"orderId": "order-123", "status": "shipped"}, }, })

</Tab>
<Tab title="Rust">
```rust title="state_trigger.rs"
use iii_sdk::{RegisterTriggerInput, TriggerRequest};
use serde_json::json;

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "state".into(),
    function_id: "orders::on-status-change".into(),
    config: json!({ "scope": "orders", "key": "status" }),
})?;

// Then run iii.trigger() from another function or worker to trigger the state change
iii.trigger(TriggerRequest {
    function_id: "state::set".into(),
    payload: json!({
        "scope": "orders",
        "key": "status",
        "value": { "orderId": "order-123", "status": "shipped" },
    }),
    action: None,
    timeout_ms: None,
}).await?;

</Tab> </Tabs>

Result

When any Function writes to the watched scope/key pair via state::set or state::update, the Engine automatically invokes the registered handler with the new value. {/* <Info title="See also"> For advanced state operations and adapter options, see the State module reference. </Info> */}