Search docs.molo17.com

    Chained events

    Chained events let you run a sequence of additional actions after a scheduled job completes. Use them to build multi-step workflows such as stopping a pipeline, running a snapshot, then restarting CDC.

    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.

    Overview

    A chained event is an extra task that is executed once the parent scheduled job finishes successfully. Each event specifies:

    • The action to perform (for example, start, stop, snapshot, redo, maintenance mode, Query Studio, or an AI agent run)

    • The target pipeline, group, or entity

    • The execution mode (async or sync)

    • An optional webhook timeout for sync events

    Events are processed in order. If one event fails, the chain stops and the error is recorded on the parent job.

    Execution Modes

    Async

    In async mode, Chronos fires the action and immediately proceeds to the next event without waiting for the action to complete. This is the fastest mode and is useful when later steps do not depend on the result of the previous one.

    Sync

    In sync mode, Chronos registers a one-shot webhook in the Core Hub and waits for the previous action to complete before firing the next event. This is useful when later steps must run only after the previous step has finished successfully.

    When a sync event is configured, Chronos:

    1. Registers a webhook in the Core Hub that listens for the completion event of the preceding step.

    2. Fires the chained event.

    3. Waits for the Core Hub callback.

    4. Proceeds to the next event once the callback is received or the configured timeout is reached.

    The default webhook timeout is 3600 seconds (one hour). You can override it per event.

    Supported Actions

    Chained events support the same actions as scheduled jobs:

    Action Maps to

    Pause

    entity_stop, group_stop, pipeline_stop

    CDC

    entity_start, group_start, pipeline_start

    Snapshot with truncate

    entity_snapshot, group_snapshot, pipeline_snapshot with INSERT

    Snapshot without truncate

    entity_snapshot, group_snapshot, pipeline_snapshot with UPSERT

    Snapshot with truncate + CDC

    entity_redo, group_redo, pipeline_redo with INSERT

    Snapshot without truncate + CDC

    entity_redo, group_redo, pipeline_redo with UPSERT

    Put under maintenance

    pipeline_enter_maintenance

    Resume from maintenance

    pipeline_exit_maintenance

    Query Studio

    query_studio; run a saved Query Studio query or custom SQL through an explicitly selected SQL-capable agent

    AI agent run

    ai_agent_run; start a published AI agent by alias

    The target level (entity, group, or pipeline) is determined by the selected groups and entities, just like for regular scheduled jobs — except Query Studio, which is pipeline plus one SQL-capable agent only, and AI agent runs, which do not require a pipeline.

    You can place more events after a Query Studio event. Query Studio has no Core Hub completion webhook: sync waits on the HTTP execute (120 seconds). If Query Studio is the preceding step, the next sync event skips the webhook wait. See Query Studio actions for query selection, write safeguards, and chained-event steps.

    An AI agent run can also be a chained event. Use sync mode when a later action depends on the published agent completing successfully. See AI agent runs for the agent fields, safe payload interpolation, and loop safeguards.

    Creating a Job with Chained Events

    Chained events are part of the job payload when creating or updating a schedule via the REST API:

    POST /api/jobs
    
    {
      "name": "Nightly stop, snapshot, and restart",
      "task_type": "pipeline_stop",
      "cron_expression": "0 2 * * *",
      "pipeline_id": "pipeline-123",
      "enabled": true,
      "chained_events": [
        {
          "task_type": "pipeline_snapshot",
          "pipeline_id": "pipeline-123",
          "execution_mode": "sync",
          "webhook_timeout_seconds": 3600,
          "snapshot_write_method": "UPSERT"
        },
        {
          "task_type": "pipeline_start",
          "pipeline_id": "pipeline-123",
          "execution_mode": "sync",
          "webhook_timeout_seconds": 3600,
          "with_snapshot": false
        }
      ]
    }

    Each event in the chained_events array is executed in the order it appears. To clear chained events, pass an empty array in an update request.

    Chained Event Fields

    Field Type Description

    task_type

    string

    Task to perform, such as pipeline_snapshot, entity_start, group_stop, pipeline_enter_maintenance, query_studio, or ai_agent_run

    pipeline_id

    string

    ID of the pipeline to operate on. Optional for ai_agent_run

    entity_ids

    array

    Entity IDs for entity-level operations

    group_ids

    array

    Group IDs for group-level operations

    with_snapshot

    boolean

    Whether to include a snapshot when starting or redoing

    snapshot_write_method

    string

    UPSERT or INSERT; applies to snapshot and redo actions

    execution_mode

    string

    async or sync

    webhook_timeout_seconds

    integer

    How long to wait for a webhook callback in sync mode (default: 3600). Ignored when the preceding task is Query Studio (HTTP completion).

    agent_id

    string

    Required when task_type is query_studio. SQL-capable agent.

    query_sql

    string

    Custom SQL or saved-query snapshot when task_type is query_studio.

    saved_query_id

    string

    Optional Query Studio saved query when task_type is query_studio.

    query_read_only

    boolean

    Query Studio only. Defaults to true. false allows writes.

    agent_alias

    string

    Required published agent alias when task_type is ai_agent_run.

    agent_version

    integer

    AI agent run only. Optional published agent version.

    prompt_template

    string

    AI agent run only. Optional prompt with allow-listed {{dotted.path}} tokens.

    payload_allow_list

    array

    AI agent run only. Payload paths available for interpolation.

    agent_input

    object

    AI agent run only. Optional input object; string values can contain allow-listed tokens.

    idempotency_key

    string

    AI agent run only. Optional Core Hub idempotency key or template.

    allow_ai_run_loop

    boolean

    AI agent run only. Allow the first AI run platform-event hop; defaults to false.

    Using the Gluesync UI

    When you create or edit a schedule in the Gluesync UI, expand the Chained Events section and click Add event for each additional step.

    For each event:

    1. Select the execution mode (Async or Sync).

    2. If Sync is selected, set the webhook timeout.

    3. Pick the action from the dropdown.

    4. Choose the target pipeline, group, or entity.

    5. For a Query Studio action, the target is pipeline-only. Select a saved query or enable Use a custom query and enter SQL, then confirm the SQL-capable agent.

    6. Use the up and down arrows to reorder events.

    The number of chained events is shown in the section header so you can review the sequence at a glance.

    How Sync Chains Work

    When a job with sync chained events runs, Chronos opens an active listening window for the webhook callbacks. The Core Hub sends a callback when the preceding action completes, and Chronos uses that signal to proceed. If the callback does not arrive within the timeout, the chain fails and the error is recorded.

    Chronos automatically registers the required webhooks when a job is created or updated, and cleans up orphaned webhooks at startup.

    Best Practices

    • Use sync mode when the next step depends on the completion of the previous one

    • Use async mode for independent steps that can run in parallel

    • Set webhook timeouts long enough to cover the longest expected operation

    • Keep chains short and focused on a single workflow

    • Test chains in a non-production environment before enabling them

    • Review the parent job’s last_error_message if a chain fails

    Troubleshooting

    Common Issues

    Issue Possible Cause Resolution

    Sync event times out

    Preceding action took longer than the configured timeout

    Increase webhook_timeout_seconds or check the Core Hub logs

    Chain fails after an async event

    The async action returned an HTTP error

    Check the Chronos logs for the event ID and response

    Webhook not received

    Core Hub cannot reach the Chronos callback URL

    Verify CHRONOS_CALLBACK_URL or network connectivity

    Orphaned webhooks accumulate

    Jobs were deleted without cleanup

    Restart Chronos to trigger the stale webhook cleanup