Calling a function directly with worker.trigger or iii trigger are documented in Using iii /
Functions. This page covers specifics about Triggers
such as registering (binding) Triggers to Functions, gating triggers, and unregistering them. Register a trigger
If you’re authoring a worker, you’ll want to refer to Creating Workers /
Triggers to learn the
difference between registering a trigger, and registering a trigger type. http endpoint, a cron job, a change in state, or any other trigger that a
worker supports. You can also write your own.
You bind triggers to functions via the function_id. The trigger declares its type, its config
(defined by each type), and the function to invoke.
Node / TypeScript
Python
Rust
import { registerWorker } from "iii-sdk";
const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url);
worker.registerTrigger({
type: "http",
function_id: "math::add",
config: { api_path: "/math/add", http_method: "POST" },
});
import os
from iii import register_worker, InitOptions
worker = register_worker(
os.environ.get("III_URL"),
InitOptions(worker_name="my-worker"),
)
worker.register_trigger({
"type": "http",
"function_id": "math::add",
"config": {"api_path": "/math/add", "http_method": "POST"},
})
use iii_sdk::{InitOptions, RegisterTriggerInput, register_worker};
use serde_json::json;
let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());
worker.register_trigger(RegisterTriggerInput {
trigger_type: "http".into(),
function_id: "math::add".into(),
config: json!({ "api_path": "/math/add", "http_method": "POST" }),
metadata: None,
})?;
http type).
The optional metadata field on a trigger registration (null / None in the examples above)
is arbitrary JSON stored with the trigger and delivered to the receiving function as a
distinct argument alongside the payload. It is useful for providing contextual information about
the trigger or execution context to the receiving function.
A target function shared by many triggers can use it to recover which registration fired and
with what context. See
Receive per-invocation metadata
for handler-side access in each SDK.
metadata can be provided both via registerTrigger and direct trigger() invocations
Handling missing triggers
When the engine cannot register a trigger, most commonly because the trigger type’s worker is not
active in the project, it sends a TriggerRegistrationResult with an error body back to the
worker that initiated the request and logs it.
For known trigger types (ex. http, subscribe, state, durable:subscriber, stream), the
error message will include the install command for the missing worker. If it doesn’t you can find
the worker that exposes the needed type at workers.iii.dev
Bind multiple triggers to one function
It’s valid to bind multiple triggers to the same function_id and this can be done across any
number of types. Register a second trigger with the same function_id and a different type or
config; the function runs unchanged whether the call arrives over HTTP, on a cron schedule, or from
a queue message.
Node / TypeScript
Python
Rust
// Same handler runs for an HTTP POST and a weekly cron tick.
worker.registerTrigger({
type: "http",
function_id: "reports::generate",
config: { api_path: "/reports/generate", http_method: "POST" },
});
worker.registerTrigger({
type: "cron",
function_id: "reports::generate",
config: { expression: "0 0 9 * * 1" }, // Every Monday at 09:00
});
worker.register_trigger({
"type": "http",
"function_id": "reports::generate",
"config": {"api_path": "/reports/generate", "http_method": "POST"},
})
worker.register_trigger({
"type": "cron",
"function_id": "reports::generate",
"config": {"expression": "0 0 9 * * 1"}, # Every Monday at 09:00
})
use iii_sdk::RegisterTriggerInput;
use serde_json::json;
worker.register_trigger(RegisterTriggerInput {
trigger_type: "http".into(),
function_id: "reports::generate".into(),
config: json!({ "api_path": "/reports/generate", "http_method": "POST" }),
metadata: None,
})?;
worker.register_trigger(RegisterTriggerInput {
trigger_type: "cron".into(),
function_id: "reports::generate".into(),
config: json!({ "expression": "0 0 9 * * 1" }), // Every Monday at 09:00
metadata: None,
})?;
Gate a trigger with a condition
A trigger can carry an optional condition_function_id (set inside the trigger’s config). When
the trigger fires, the engine invokes the condition function first with the same payload the handler
would receive; the target function_id only runs when the condition returns truthy. The condition
is a regular registered function.
Node / TypeScript
Python
Rust
worker.registerFunction(
"orders::is-priority",
async (payload: { customer_tier: string }) => payload.customer_tier === "gold",
);
worker.registerTrigger({
type: "http",
function_id: "orders::expedite",
config: {
api_path: "/orders/expedite",
http_method: "POST",
condition_function_id: "orders::is-priority",
},
});
def is_priority(payload: dict) -> bool:
return payload.get("customer_tier") == "gold"
worker.register_function("orders::is-priority", is_priority)
worker.register_trigger({
"type": "http",
"function_id": "orders::expedite",
"config": {
"api_path": "/orders/expedite",
"http_method": "POST",
"condition_function_id": "orders::is-priority",
},
})
use iii_sdk::{RegisterFunction, RegisterTriggerInput};
use schemars::JsonSchema;
use serde::Deserialize;
use serde_json::json;
#[derive(Deserialize, JsonSchema)]
struct Payload { customer_tier: String }
worker.register_function(RegisterFunction::new(
"orders::is-priority",
|input: Payload| -> Result<bool, String> {
Ok(input.customer_tier == "gold")
},
));
worker.register_trigger(RegisterTriggerInput {
trigger_type: "http".into(),
function_id: "orders::expedite".into(),
config: json!({
"api_path": "/orders/expedite",
"http_method": "POST",
"condition_function_id": "orders::is-priority",
}),
metadata: None,
})?;
Unregister a trigger
Trigger registration returns a handle with an unregister() method. Call it to drop the trigger at
runtime; when the worker disconnects, all of its triggers are removed automatically.
Node / TypeScript
Python
Rust
const trigger = worker.registerTrigger({
type: "http",
function_id: "math::add",
config: { api_path: "/math/add", http_method: "POST" },
});
trigger.unregister();
trigger = worker.register_trigger({
"type": "http",
"function_id": "math::add",
"config": {"api_path": "/math/add", "http_method": "POST"},
})
trigger.unregister()
use iii_sdk::RegisterTriggerInput;
use serde_json::json;
let trigger = worker.register_trigger(RegisterTriggerInput {
trigger_type: "http".into(),
function_id: "math::add".into(),
config: json!({ "api_path": "/math/add", "http_method": "POST" }),
metadata: None,
})?;
trigger.unregister();
