Trigger scripts

A trigger script polls an external source and returns whatever is new since its last run, instead of relying on that source pushing a webhook. It’s meant to run on a schedule, using state — a rich JSON object that persists from one execution to the next — to remember what it already processed, so the flow’s for loop that follows only sees genuinely new items. If nothing changed since last time, the flow run is skipped outright.

For state that’s more structured than a single tracked value — genuinely relational data you need to query, not just remember — reach for data tables instead: a workspace-scoped SQL database built into Orvanta for exactly that.

Scheduled polls

It behaves like someone checking their mailbox on a routine: open it, and if there’s a new letter, read and process it; if not, do nothing — and crucially, whatever was already opened doesn’t go back in the mailbox. A trigger script’s whole job is keeping track of that boundary between “already handled” and “not yet handled”.

Flows are scheduled from the Flow UI with a CRON expression, then activated.

Example use cases

Typical things a trigger script polls for:

New posts on a forum or site matching a keyword.
New stars on a GitHub repository.
New files uploaded to a shared drive.

Code example

This TypeScript example checks a MongoDB collection for documents inserted since the last run:

import { getState, type Resource, setState } from 'npm:orvanta-client';
import { MongoClient, ObjectId } from 'https://deno.land/x/atlas_sdk/mod.ts';

type MongodbRest = {
  endpoint: string;
  api_key: string;
};

export async function main(
  auth: MongodbRest,
  data_source: string,
  database: string,
  collection: string) {
  const client = new MongoClient({
    endpoint: auth.endpoint,
    dataSource: data_source,
    auth: { apiKey: auth.api_key }
  });
  const documents = client.database(database).collection(collection);
  const lastCheck = (await getState()) || 0;
  await setState(Date.now() / 1000);
  const id = ObjectId.createFromTime(lastCheck);
  return await documents.find({ _id: { $gt: id } });
}

getState/setState are Orvanta’s built-in helpers for reading and writing that persistent checkpoint between runs.