Schedule a Cron Task

How to run a Function on a recurring schedule.

Goal

Run a Function at regular intervals (cleanup jobs, report generation, health checks) using the Cron worker.

Steps

1. Enable the Cron worker

iii-config.yaml

workers:
  - name: iii-cron
    config:
      adapter:
        name: kv

2. Register the Function

Node / TypeScript

cron-task.ts

import { registerWorker, Logger } from 'iii-sdk'

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

iii.registerFunction('cleanup::expired-sessions', async () => {
  const logger = new Logger()
  // ...cleanup logic here...
  logger.info('Cleanup ran', { timestamp: new Date().toISOString() })
  return { deleted: 0 }
})

Python

cron_task.py

import os

from iii import Logger, register_worker

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


def cleanup_sessions(_):
    logger = Logger()
    # ...cleanup logic here...
    logger.info("Cleanup ran")
    return {"deleted": 0}


iii.register_function("cleanup::expired-sessions", cleanup_sessions)

Rust

cron_task.rs

use iii_sdk::{register_worker, InitOptions, Logger, RegisterFunction, RegisterTriggerInput};
use serde_json::{json, Value};
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());

    let reg = RegisterFunction::new_async("cleanup::expired-sessions", |_: Value| async move {
        let logger = Logger::new();
        // ...cleanup logic here...
        logger.info("Cleanup ran", None);
        Ok(json!({ "deleted": 0 }))
    });
    iii.register_function(reg);

    signal::ctrl_c().await?;
    Ok(())
}

3. Register the Cron trigger

Node / TypeScript

cron-trigger.ts

iii.registerTrigger({
  type: 'cron',
  function_id: 'cleanup::expired-sessions',
  config: { expression: '* * * * * * *' }, // runs every second
})

Python

cron_trigger.py

iii.register_trigger({
    "type": "cron",
    "function_id": "cleanup::expired-sessions",
    "config": {"expression": "* * * * * * *"},  # runs every second
})

Rust

cron_trigger.rs

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "cron".into(),
    function_id: "cleanup::expired-sessions".into(),
    config: json!({ "expression": "* * * * * * *" }), // runs every second
    metadata: None,
})?;

This runs the Function every second. The expression field uses a 7-field cron format (second minute hour day month weekday year).

Common schedules

Expression	Frequency
* * * * * * *	Every second
0 * * * * * *	Every minute
0 */5 * * * * *	Every 5 minutes
0 0 * * * * *	Every hour
0 0 */6 * * * *	Every 6 hours
0 0 0 * * * *	Daily at midnight
0 0 9 * * 1 *	Every Monday at 9 AM

Result

The Function executes automatically on the defined schedule. The Engine handles scheduling, no external cron daemon needed.

For advanced scheduling options, see the Cron worker reference.