Search docs.molo17.com

    Schedules

    Chronos offers two ways to define when a job should run: a user-friendly daily schedule picker and standard cron expressions. Both can be used through the REST API and the Gluesync UI.

    How-to guide

    For a step-by-step walkthrough tested on a running Gluesync, see the how-to guide Automate pipeline actions with schedules, chained events, and webhooks.

    Scheduling Options

    User-Friendly Daily Schedule Format

    Chronos supports a user-friendly schedule format that doesn’t require knowledge of cron expressions:

    {
      "schedule": {
        "days_of_week": ["monday", "wednesday", "friday"],
        "hour": 8,
        "minute": 30
      }
    }

    Parameters:

    • days_of_week: Array of days when the job should run. Valid values are: "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday". An empty array means every day.

    • hour: Hour of the day (0-23)

    • minute: Minute of the hour (0-59)

    Examples:

    • Every day at 8:30 AM: {"days_of_week": [], "hour": 8, "minute": 30}

    • Every Monday, Wednesday, and Friday at 8:30 AM: {"days_of_week": ["monday", "wednesday", "friday"], "hour": 8, "minute": 30}

    • Every weekend at midnight: {"days_of_week": ["saturday", "sunday"], "hour": 0, "minute": 0}

    This is the same format used by the Gluesync UI scheduler form: select the days of the week, enter the time in hh:mm format, and pick AM or PM.

    Cron Expression Format

    Chronos also supports standard cron expressions for more advanced scheduling needs:

    ┌───────────── minute (0 - 59)
    │ ┌───────────── hour (0 - 23)
    │ │ ┌───────────── day of the month (1 - 31)
    │ │ │ ┌───────────── month (1 - 12)
    │ │ │ │ ┌───────────── day of the week (0 - 6) (Sunday to Saturday)
    │ │ │ │ │
    │ │ │ │ │
    * * * * *

    Examples:

    • 0 * * * * - Run once every hour

    • 0 0 * * * - Run once a day at midnight

    • 0 0 * * 0 - Run once a week on Sunday at midnight

    • 0 0 1 * * - Run once a month on the 1st at midnight

    Use cron expressions when you need more flexibility than the daily picker provides, such as monthly schedules, specific day-of-month rules, or non-daily intervals.

    Day of the month and day of the week (day_or)

    When a cron expression sets both the day of the month and the day of the week (neither field is *), the day_or setting of the schedule decides how the two fields combine:

    day_or The job runs on days where Example: 0 9 1-7 * 6

    true (default)

    the day of the month or the day of the week matches, as in standard cron

    at 09:00 on days 1 to 7 of every month, and on every Saturday

    false

    the day of the month and the day of the week both match

    at 09:00 on the first Saturday of every month

    day_or has no effect when either day field is *: 0 0 1 * * runs on the 1st and 0 0 * * 6 on Saturdays either way. Fields such as 1-7, 1,15 or */2 count as set.

    Set day_or when creating a job, or change it later with a job update:

    POST /api/jobs
    
    {
      "name": "First Saturday of the month",
      "task_type": "pipeline_snapshot",
      "cron_expression": "0 9 1-7 * 6",
      "day_or": false,
      "pipeline_id": "pipeline-123",
      "enabled": true
    }

    In the Gluesync UI the setting is the Run when either the day of month or the day of week matches checkbox under the cron fields in the CRON tab: checked is true, unchecked is false. The checkbox is available when both day fields are set, and the schedules list shows (both days must match) next to the cron expression of schedules with day_or set to false.

    day_or is available from Chronos 0.3.1. On the upgrade to 0.3.1, schedules created with an earlier version are set to day_or: false, because earlier versions ran a schedule only on days matching both fields. They keep running on the same days as before. New schedules default to true.

    Creating a Scheduled Job

    Jobs can be created via the REST API:

    POST /api/jobs
    
    {
      "name": "Monday-Wednesday-Friday Job",
      "description": "Runs on specific days at 8:30 AM",
      "task_type": "entity_snapshot",
      "schedule": {
        "days_of_week": ["monday", "wednesday", "friday"],
        "hour": 8,
        "minute": 30
      },
      "pipeline_id": "pipeline-123",
      "entity_id": "entity-456",
      "with_snapshot": true,
      "enabled": true
    }

    This will automatically be converted to the cron expression 30 8 * * 1,3,5 internally.

    The same request using a cron expression looks like this:

    POST /api/jobs
    
    {
      "name": "Daily at midnight",
      "task_type": "pipeline_snapshot",
      "cron_expression": "0 0 * * *",
      "pipeline_id": "pipeline-123",
      "enabled": true
    }

    Running Query Studio queries

    Use the Query Studio action type to schedule SQL through an explicitly selected SQL-capable agent. Groups and entities are not used. Selecting a saved query fills agent_id when the query contains one; otherwise select an agent from the agent picker.

    At fire time Chronos prefers the live Query Studio saved query from Core Hub and falls back to the SQL snapshot stored on the job. Execution is a Core Hub Query Studio POST (120 second timeout), not a crontab command.

    UI action API task_type

    Query Studio

    query_studio

    The Query Studio task fields follow the same scheduled-job payload as other task types:

    {
      "task_type": "query_studio",
      "pipeline_id": "pipeline-123",
      "agent_id": "agent-456",
      "query_sql": "SELECT COUNT(*) FROM staging_orders",
      "saved_query_id": "saved-query-789",
      "query_read_only": true
    }
    Field Required Description

    task_type

    Yes

    Set to query_studio.

    pipeline_id

    Yes

    Pipeline in which the Query Studio action runs.

    agent_id

    Yes

    Explicit SQL-capable agent that runs the query.

    query_sql

    Conditional

    SQL statement to run. Required for custom SQL. When saved_query_id is set, Chronos also accepts a missing SQL snapshot; the UI always sends one.

    saved_query_id

    No

    Selected saved query. Omit for custom SQL.

    query_read_only

    No

    Whether to enforce read-only execution. Defaults to true.

    In the UI, selecting I acknowledge this query can modify data sets query_read_only to false.

    See Query Studio actions for saved and custom query selection, query_read_only, write acknowledgment, and complete UI steps.

    Running published AI agents

    Use the ai_agent_run task type to start a published AI agent on a daily or cron schedule. agent_alias is required; pipeline_id is optional and can be empty.

    {
      "task_type": "ai_agent_run",
      "agent_alias": "agent/daily-report",
      "agent_input": {
        "audience": "operations"
      }
    }

    See AI agent runs for input templates, payload allow-listing, event triggers, and loop safeguards.

    Timezone Support

    All schedules are interpreted in the timezone configured by the TIMEZONE environment variable. The Gluesync UI also lets you select a timezone for the scheduler. Once a job is created, its run times are fixed in that timezone; changing the timezone later does not affect existing jobs.

    If no timezone is set, Chronos defaults to UTC.

    Repeating Options from the UI

    For common scheduling needs, use the simple schedule picker in the Gluesync UI:

    Day Selection:

    • A row of checkboxes labeled with day abbreviations (Mon, Tue, Wed, etc.) is displayed

    • Click on each day of the week when you want the task to run

    • Selected days will be highlighted in the interface

    Time Configuration:

    • Time input field appears near the day selection

    • Enter the time in hh:mm 12-hour format (e.g., 2:30)

    • Select either AM or PM from the dropdown menu

    • The time picker will validate your input to ensure it’s in the correct format

    • The scheduled time will be based on the timezone you’ve selected in the top right corner

    Example Scenarios:

    • For a task that runs every weekday at 9:00 AM:

    • Check Mon, Tue, Wed, Thu, Fri

    • Enter 09:00 in the time field

    • For a task that runs on weekends at 11:30 PM:

    • Check Sat, Sun

    • Enter 11:30 in the time field and select PM

    Best Practices

    • Use the daily schedule picker for simple recurring jobs

    • Use cron expressions for monthly, hourly, or complex recurrence rules

    • When a cron expression sets both the day of the month and the day of the week, check day_or: uncheck it in the UI (or send "day_or": false) for rules such as "the first Saturday of the month"

    • Set a timezone explicitly so jobs run at the expected local time

    • Monitor the next_run field to verify your schedule is interpreted correctly

    • Test new schedules with a future date before enabling them in production

    • Prefer saved Query Studio queries to make recurring SQL easier to review and update