Schedule Triggers

12 min

Schedule triggers initiate a playbook at a configured time using cron expressions. They are ideal for automating repetitive tasks, improving productivity, and reducing human errors. For example, you can use a schedule trigger to automatically generate reports, eliminate the need to manually retrieve data, or perform periodic maintenance tasks.

Key Benefits

Automated Execution: Run playbooks automatically at specified intervals without manual intervention

Flexible Scheduling: Support for various schedule frequencies (minutely, hourly, daily, weekly, monthly, yearly, or custom cron expressions)

UTC Timezone: All schedules are evaluated in UTC for consistency across different server locations

Reliable: Uses Hangfire job scheduler for reliable execution of scheduled tasks

Creating a Schedule Trigger

To set a cron job for your playbook, follow these steps:

In a playbook, from the Add panel, click and drag Schedule to the canvas.

Hover over the plus icon to add it to the canvas. The Trigger panel will display on the right side of the canvas, where you can configure your schedule trigger.

Configure the schedule trigger:

Schedule Type

The Schedule Type is set to cron (this is the only supported schedule type).

Schedule Frequency

Select the desired time schedule from the following options:

Minutely: Runs every minute

Hourly: Runs every hour at a specified minute (e.g., every hour at :15 minutes)

Daily: Runs once per day at a specified time (e.g., every day at 8:00 AM UTC)

Weekly: Runs once per week on a specified day and time (e.g., every Monday at 8:00 AM UTC)

Monthly: Runs once per month on a specified day and time (e.g., 1st of every month at 12:00 AM UTC)

Yearly: Runs once per year on a specified date and time (e.g., January 1st at 12:00 AM UTC)

Custom: Allows you to define a custom cron expression

Configuration Fields

Depending on the selected schedule frequency, you'll configure:

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

Hour: The hour of the day (0-23) in UTC

Day of Week: For weekly schedules, select the day (Sunday = 0, Monday = 1, etc.)

Day of Month: For monthly/yearly schedules, select the day (1-31)

Month: For yearly schedules, select the month (1-12)

Note: The UI displays the current UTC time to help you configure schedules correctly.

Custom Cron Expression

For Custom schedule type, you can enter a standard cron expression in the format:

Cron Expression Format:

Minute: 0-59

Hour: 0-23 (UTC)

Day of Month: 1-31

Month: 1-12

Day of Week: 0-6 (0 = Sunday, 1 = Monday, etc.)

Examples:

0 0 * * * - Every day at midnight UTC

0 8 * * 1 - Every Monday at 8:00 AM UTC

0 0 1 * * - First day of every month at midnight UTC

*/15 * * * * - Every 15 minutes

0 9-17 * * 1-5 - Every hour from 9 AM to 5 PM UTC, Monday through Friday

When finished, click Save to complete your schedule configuration.

The schedule trigger is now configured and will execute your playbook according to the specified cron expression.

Detailed Example with Native Actions: Automating Weekly Data Collection and Processing

This example demonstrates how to use a schedule trigger combined with native actions (HTTP, Condition, Loop, Transform, and Create Variables) to automate data collection, processing, and reporting.

Scenario

You want to collect data from an external API every Monday at 8:00 AM, process it, and generate a report. The report will either be stored or emailed. The playbook ensures that only valid data is processed, and any errors will be logged for review.

Steps:

Step 1: Configure the schedule trigger to run every Monday at 8:00 AM UTC.

In the Schedule Trigger panel, select Weekly.

Select Monday as the day of week.

Set the time to 8:00 AM (remember, this is UTC time).

The UI displays the current UTC time to help you verify your configuration.

Step 2: Add an HTTP Action to make a GET request to an external API that provides data for the report.

Drag the HTTP action into the playbook.

Configure the HTTP action to send a GET request to the API endpoint (e.g., https://api.example.com/data).

Include any required headers (e.g., Authorization tokens).

Step 3: Use the Condition Action to verify if the API returns valid data.

Drag a Condition action into the flow.

Set the condition to check if the API response contains valid data (e.g., response["data"] is not null).

Step 4: If valid data is present, use a Loop Action to iterate through each record in the API response.

Drag a Loop action into the playbook.

Configure the loop to iterate over the records in the API response (e.g., response["data"]).

Step 5: Within the loop, apply a Transform Action to format the data.

Drag a Transform action into the loop.

Configure it to extract and format necessary fields such as date, amount, and category from each record.

Step 6: Use the Create Variables Action to store the transformed data.

Drag a Create Variables action into the flow after the transformation.

Create variables for date, amount, category, etc.

Step 7: Depending on the requirement, send the report via email or store it in a database.

For email, add an Email Action and configure it to send the report.

For storage, use an HTTP Action or connector to store the report in a database.

Step 8: If the condition in step 3 is not met, log the error and notify the team.

Use the Else branch of the Condition action to log the error and send a notification.

Example Flow

Schedule Trigger: Executes every Monday at 8:00 AM UTC.

HTTP Action: Makes a GET request to collect report data from an external API.

Condition Action: Checks if the response contains valid data; if not, logs an error.

Loop Action: Iterates over data records returned by the API.

Transform Action: Formats data fields (e.g., "date," "amount," "category").

Create Variables Action: Stores the transformed data as variables for further processing.

Final Step: Store the report in a database or send it via email to stakeholders.

Schedule Trigger Outputs

When a schedule trigger executes, it provides the following event data that can be accessed in your playbook:

Event Data

$event.data.cron: The cron expression that triggered this execution (string)

Event Metadata

Event Type: schedule

Event Action: cron

Event FQN: turbine.schedule.cron

Event Source: turbine

Accessing Schedule Data in Playbooks

You can access schedule trigger data in your playbook actions:

Examples:

Note: Schedule triggers don't provide additional data beyond the cron expression. The primary use case is to trigger playbooks at specific times rather than passing data.

Best Practices

Use UTC Time: Always configure schedules in UTC timezone. The UI displays the current UTC time to help you configure schedules correctly.

Test Your Schedule: Before deploying to production, verify that your schedule triggers at the expected times by checking playbook run history.

Consider Timezone Conversion: If you need to run playbooks at specific local times, convert your local time to UTC when configuring the schedule.

Use Descriptive Names: Give your playbooks descriptive names that indicate when they run (e.g., "Daily Report Generator - 8 AM UTC").

Avoid Overlapping Schedules: Be mindful of playbook execution time to avoid overlapping executions if a previous run hasn't completed.

Monitor Execution: Regularly monitor scheduled playbook executions to ensure they're running as expected and completing successfully.

Use Appropriate Frequencies: Choose the minimum frequency needed for your use case. Running playbooks too frequently can impact system performance.

Handle Errors Gracefully: Ensure your scheduled playbooks handle errors appropriately, as they run unattended.

Troubleshooting

Playbook Not Executing:

Verify the playbook is published and enabled

Check that the cron expression is valid

Verify the schedule time has passed (schedules are evaluated in UTC)

Check playbook run history for any execution errors

Wrong Execution Time:

Remember that schedules are evaluated in UTC, not your local timezone

Convert your desired local time to UTC before configuring the schedule

Use the UTC time display in the UI to verify your configuration

Invalid Cron Expression:

Verify the cron expression follows the standard 5-field format: minute hour day-of-month month day-of-week

Ensure numeric values are within valid ranges (minute: 0-59, hour: 0-23, etc.)

Check that special characters (,, -, *, /) are used correctly

Schedule Not Saving:

Ensure all required fields are filled in

Verify the cron expression is valid

Check for any validation errors displayed in the UI

Multiple Executions:

Verify you don't have duplicate schedule triggers configured

Check that the cron expression doesn't match multiple times unintentionally

Review playbook run history to identify execution patterns