Cron

Schedule functions with cron expressions.

Schedule functions to execute at specific times using cron expressions.

iii-cron

Sample Configuration

- name: iii-cron
  config:
    adapter:
      name: redis
      config:
        redis_url: ${REDIS_URL:redis://localhost:6379}

Configuration

adapter · Adapter

The adapter to use for distributed locking. Defaults to kv. Use redis for multi-instance deployments.

Adapters

kv

When running multiple engine instances, the kv adapter does not provide reliable distributed locking — the same cron job may execute on every instance simultaneously. Use the redis adapter for multi-instance deployments.

Built-in adapter using process-local locks. Suitable for single-instance deployments.

name: kv
config:
  lock_ttl_ms: 30000
  lock_index: cron_locks

Configuration

lock_ttl_ms · integer

Duration in milliseconds for which a lock is held before it expires. Defaults to 30000 (30 seconds).

lock_index · string

Key namespace used to store lock entries in the KV store. Defaults to cron_locks.

redis

Uses Redis for distributed locking to prevent duplicate job execution across multiple engine instances.

name: redis
config:
  redis_url: ${REDIS_URL:redis://localhost:6379}

Configuration

redis_url · string

The URL of the Redis instance to use for distributed locking.

Trigger Type

This Worker adds a new Trigger Type: cron.

Show Trigger Config

expression · string · required

Cron expression defining the schedule. Accepts 6-field (second minute hour day month weekday) or 7-field (second minute hour day month weekday year) format — the year field is optional.

* * * * * * [*]
│ │ │ │ │ │  │
│ │ │ │ │ │  └── Year (optional, * for any)
│ │ │ │ │ └──── Day of week (0–7, Sun=0 or 7)
│ │ │ │ └────── Month (1–12)
│ │ │ └──────── Day of month (1–31)
│ │ └────────── Hour (0–23)
│ └──────────── Minute (0–59)
└──────────── Second (0–59)

Both "0 0 * * * *" (6-field) and "0 0 * * * * *" (7-field) are valid and equivalent.

condition_function_id · string

Function ID for conditional execution. The engine invokes it with the cron event; if it returns false, the handler function is not called.

Show Trigger Event Payload

The following fields are passed to the handler function (and to condition_function_id if set) each time the trigger fires.

trigger · string

Always "cron".

job_id · string

The ID of the cron trigger that fired.

scheduled_time · string

The time the job was scheduled to run, in RFC 3339 format.

actual_time · string

The actual time the job began executing, in RFC 3339 format.

Sample Code

TypeScript

const fn = iii.registerFunction(
  { id: 'jobs::cleanupOldData' },
  async (event) => {
    console.log('Running cleanup scheduled at:', event.scheduled_time)
    return {}
  },
)

iii.registerTrigger({
  type: 'cron',
  function_id: fn.id,
  config: { expression: '0 0 2 * * * *' },
})

Python

def cleanup_old_data(event):
    print('Running cleanup scheduled at:', event['scheduled_time'])
    return {}

iii.register_function("jobs::cleanupOldData", cleanup_old_data)
iii.register_trigger({'type': 'cron', 'function_id': 'jobs::cleanupOldData', 'config': {'expression': '0 0 2 * * *'}})

Rust

iii.register_function(
    RegisterFunctionMessage::with_id("jobs::cleanupOldData".into()),
    |event: Value| async move {
        println!("Running cleanup scheduled at: {}", event["scheduled_time"]);
        Ok(json!({}))
    },
);

iii.register_trigger(RegisterTriggerInput {
    trigger_type: "cron".into(),
    function_id: "jobs::cleanupOldData".into(),
    config: json!({ "expression": "0 0 2 * * * *" }),
    metadata: None,
})?;

Common Cron Expressions

Expression	Description
0 * * * * *	Every minute (6-field)
0 0 * * * *	Every hour (6-field)
0 0 2 * * *	Every day at 2 AM (6-field)
0 * * * * * *	Every minute (7-field)
0 0 * * * * *	Every hour (7-field)
0 0 0 * * * *	Every day at midnight
0 0 0 * * 0 *	Every Sunday at midnight
0 */5 * * * * *	Every 5 minutes
0 0 9-17 * * 1-5 *	Every hour from 9 AM to 5 PM, Monday to Friday

Distributed Execution

When running multiple iii Engine instances, the Cron Worker uses distributed locking to ensure jobs execute only once: