Automation Scheduling Guide

This guide explains how to schedule automated tasks within the platform. Whether you need a report generated every Monday morning or a specific follow-up email sent 3 days from now, the Scheduling System handles it.

Quick Summary

There are three main components you will interact with:

  1. Functions: The actual code or script you want to run.
  2. Recurring Schedules: Jobs that run automatically on a repeating loop (e.g., "Every hour").
  3. Scheduled Items: Jobs that run once at a specific future date and time (e.g., "Next Tuesday at 2 PM").

1. Creating a Function (The "What")

Before you can schedule anything, you need to define what should happen. This is done by creating a Function.

A Function is a container for your Python code. When the scheduler triggers, it executes this code.

Key Requirement: Your code must define an execute function that accepts current_user and **kwargs.

# Example Function Code
from valstorm.models import User

def execute(current_user: User, **kwargs):
    # 'kwargs' contains any data you pass when scheduling
    target_email = kwargs.get('target_email')
    
    print(f"Hello {current_user.name}, sending email to {target_email}")
    
    return {"status": "success"}

2. Recurring Schedules (The "Loop")

Use Schedule Trigger Settings when you want a task to repeat automatically.

How to set it up:

  1. Name: Give your schedule a descriptive name (e.g., "Daily Cleanup").
  2. Function: Select the Function you created in Step 1.
  3. Cron Schedule: Define when it runs using standard Cron syntax.
  • 0 8 * * 1 = Every Monday at 8:00 AM UTC.
  • */15 * * * * = Every 15 minutes.
  • (Tip: Use a site like crontab.guru to generate these strings).
  1. Data (Optional): If your function needs specific inputs (like a report type or email address), enter them here as JSON.
  2. Active: Ensure this is set to true. Setting it to false will pause the schedule without deleting it.

Example Input:

  • Name: "Weekly Report"
  • Cron: 0 12 * * 5 (Every Friday at 12:00 PM)
  • Function: Generate Report Script
  • Data: {"report_type": "summary"}

3. Scheduled Items (The "One-Off")

Use Scheduled Items when you need to "queue up" an action for the future. This is perfect for drip campaigns, follow-up reminders, or delayed processing.

How to set it up:

  1. Name: Describe this specific run (e.g., "Follow-up for Lead #1023").
  2. Function: Select the Function to run.
  3. Run Date Time: Pick the exact date and time (UTC) you want this to execute.
  4. Data: Pass dynamic data specific to this run (e.g., the ID of the lead you are following up with).
  5. Status: Set to Queued.

Lifecycle of a Scheduled Item:

  1. Queued: The item is waiting for its time.
  2. In Progress: The system has picked it up and is currently running the code.
  3. Completed: The code finished successfully.
  4. Failed: The code encountered an error.

FAQ

Q: What happens if I change the code in my Function? A: The scheduler always loads the latest version of your code at the moment of execution. You do not need to restart or recreate the schedule.

Q: Can I pause a Recurring Schedule? A: Yes. Simply update the Schedule Trigger Setting record and set Active to false.

Q: How do I pass data to my script? A: Use the Data JSON field in either the Recurring Schedule or Scheduled Item. Inside your Python code, you access this via the kwargs variable (e.g., kwargs.get('my_key')). Generally speaking, this is static data for Recurring Schedules and dynamic data for Scheduled Items. If you'd like dynamic data, fetch it during the execution of your function.

Q: I want to run a process 1 day after a lead is created. How do I do that? A: You will want to use the Scheduled Item for this. Documentation on this is a WIP, but the general idea is to create a new Scheduled Item record with the run_date_time, set it to tomorrow, link it to a function or automation, and set its status to Queued. A system for automating this creation is coming soon.

Q: What timezone should I use? A: All schedules and execution times are in UTC. When using the UI, it will display times in your local timezone for convenience, but all stored and processed times are in UTC. When using the API, ensure you provide UTC timestamps.