cron-steps

Cron Steps Guide

Cron Steps enable scheduled task execution using cron expressions.

They're typically used for recurring jobs like nightly reports, data synchronization, etc.

Cron steps can hold logic, but they do NOT have any retry mechanisms in place, if the logic is likely to fail, it's recommended to use CRON Step to emit an event to a topic that will ultimately trigger an Event Step that will handle the logic.

Creating Cron Steps

Steps need to be created in the steps folder, it can be in subfolders.

• Steps in TS and JS should end with .step.ts and .step.js respectively
• Steps in Python should end with _step.py

Definition

Defining a CRON Step is done by two elements. Configuration and Handler.

Configuration

TypeScript/JavaScript: You need to export a config constant via export const config that is a CronConfig type.

Python: You need to define a config dictionary with the same properties as the TypeScript CronConfig.

export type Emit = string | { 
  /**
   * The topic name to emit to.
   */
  topic: string;

  /**
   * Optional label for the emission, could be used for documentation or UI.
   */
  label?: string;

  /**
   * This is purely for documentation purposes, 
   * it doesn't affect the execution of the step.
   * 
   * In Workbench, it will render differently based on this value.
   */
  conditional?: boolean;
  }


export type CronConfig = {
  /**
   * Should always be cron
   */
  type: 'cron'

  /**
   * A unique name for this cron step, used internally and for linking handlers.
   */
  name: string

  /**
   * Optional human-readable description.
   */
  description?: string

  /**
   * The cron expression for scheduling.
   */
  cron: string

  /**
   * Optional: Topics that are virtually emitted, perhaps for documentation or lineage, but not strictly required for execution.
   */
  virtualEmits?: Emit[]

  /**
   * Topics this cron step can emit events to.
   */
  emits: Emit[]

  /**
   * Optional: An array of flow names this step belongs to.
   */
  flows?: string[]

  /**
   * Files to include in the step bundle.
   * Needs to be relative to the step file.
   */
  includeFiles?: string[]
}