Scheduled Tasks

Scheduled tasks allow you to automate team executions by running them at specified intervals. Each scheduled task runs a team on a predefined schedule using cron expressions.

---

What are Scheduled Tasks?

Scheduled tasks are automated executions of your teams. Instead of manually running a team every day or week, you can create a scheduled task that runs the team automatically at the times you specify.

Common use cases:

• Daily report generation at 9 AM
• Weekly data sync every Monday
• Hourly monitoring and alerts
• Monthly summary generation on the 1st of each month

---

Viewing Scheduled Tasks

The scheduled tasks list shows all your automated tasks with their current status and execution history.

List View

The main scheduled tasks page displays:

Column	Description
Name	Task name and description
Team	Which team this task executes
Schedule	Cron expression showing when the task runs
Status	active, paused, or errored
Execution Count	Total number of times this task has run
Success Rate	Percentage of successful executions
Last Execution	When the task last ran
Next Execution	When the task will run next (calculated from cron expression)

Status Indicators

Status	Meaning	Visual
Active	Task is running on schedule	Green indicator
Paused	Task is temporarily disabled	Gray indicator
Errored	Last execution failed	Red indicator

Search and Filters

Search: Search by task name, description, or team name

Filter options:

• All Tasks: Show everything
• Active: Only running tasks
• Paused: Only paused tasks
• Error: Tasks with recent failures
• Recently Created: Tasks created in the last 7 days

---

Creating a Scheduled Task

Navigate to Scheduled Tasks → Create Scheduled Task to set up a new automated task.

Required Fields

Basic Information

Task Name (required)

• Short, descriptive name for the task
• Example: Daily Report Generator

Description (required)

• Explain what this task does and its purpose
• Example: Generates and emails the daily sales report every morning

Status

• active: Task will run on schedule
• paused: Task is disabled and won't run

Team Selection

Select Team (required)

• Choose which team this task will execute
• The team must exist before creating the scheduled task
• Only your teams are available for selection

Schedule Configuration

Cron Expression (required)

• Defines when the task runs
• Uses standard cron format: minute hour day month day-of-week
• Example: 0 9 * * 1-5 = 9 AM every weekday

Common cron examples:

Pattern	Meaning
0 * * * *	Every hour on the hour
0 9 * * *	Every day at 9 AM
0 9 * * 1-5	Every weekday at 9 AM
0 9 * * 1	Every Monday at 9 AM
*/15 * * * *	Every 15 minutes
0 0 1 * *	First day of every month at midnight

Task Input (optional)

Input Data

• Optional data to pass to the team when it executes
• Can be JSON, text, or any format your team expects
• This input is provided to the team on every execution
• Useful for passing configuration or parameters

Example input:

{
  "report_type": "sales",
  "recipients": ["manager@company.com"],
  "include_charts": true
}

Form Completion Progress

The form shows a completion percentage based on required fields:

• Name: 25%
• Description: 25%
• Cron Expression: 30%
• Team: 20%

---

Editing a Scheduled Task

Click on any task row or use the Edit button to modify a scheduled task.

What you can edit:

• Task name and description
• Cron schedule (changes when it runs next)
• Team assignment (switch to a different team)
• Task input data
• Status (activate/pause the task)

Changes take effect immediately - If you change the cron expression, the next execution time is recalculated.

---

Execution History

Click View Executions on any task to see its execution history.

Execution List

Each execution record shows:

Field	Description
Started At	When the execution began
Completed At	When it finished (or blank if still running)
Duration	How long it took
Status	pending, running, completed, or failed
Output	Result data from the team execution
Error Message	If failed, what went wrong

Execution Status

Status	Meaning
Pending	Scheduled but not started yet
Running	Currently executing
Completed	Successfully finished
Failed	Execution encountered an error

---

Pausing and Resuming Tasks

Pause a Task

To temporarily stop a scheduled task without deleting it:

1. Edit the task
2. Change Status to paused
3. Save

The task will not execute while paused. You can resume it at any time.

Resume a Task

1. Edit the paused task
2. Change Status to active
3. Save

The task will resume on its next scheduled time.

---

Deleting Scheduled Tasks

To delete a scheduled task:

1. Click the Delete button on the task row
2. Confirm deletion by typing the task name
3. Click Delete Forever

Warning: Deletion is permanent and cannot be undone. All execution history will also be deleted.

---

Performance Metrics

Each scheduled task tracks performance metrics:

Execution Metrics

• Total Executions: How many times the task has run
• Successful Executions: How many completed without errors
• Failed Executions: How many encountered errors
• Success Rate: Percentage of successful executions
• Average Duration: Typical execution time

Health Indicators

• Green: 90%+ success rate
• Yellow: 70-89% success rate
• Red: Below 70% success rate or recent failures

---

Troubleshooting

Task Not Running

Check these:

1. Status is Active - Paused tasks don't run
2. Cron expression is valid - Use the helper examples
3. Team still exists - If the team was deleted, task won't run
4. Next execution time - Verify it's in the future

Task Keeps Failing

1. Check execution history - Look at error messages
2. Test the team manually - Run the team without the schedule
3. Verify input data - Ensure it's in the correct format
4. Check team configuration - Team may have missing tools or invalid settings

Cron Expression Not Working

Common mistakes:

• Mixing up day of month and day of week
• Using 24-hour time (0-23, not 1-12)
• Forgetting the minute field (it comes first)

Tip: Use the provided examples as a starting point and modify one field at a time.

---

API Integration

Scheduled tasks use these API endpoints:

List tasks:

GET /api/scheduled-tasks?sort_by=updated_at&sort_order=desc

Create task:

POST /api/scheduled-tasks
{
  "name": "Daily Report",
  "description": "Generates daily sales report",
  "cron_expression": "0 9 * * 1-5",
  "status": "active",
  "team_id": 123,
  "input": "optional data"
}

Update task:

PUT /api/scheduled-tasks/{id}
{
  "name": "Updated name",
  "cron_expression": "0 10 * * 1-5"
}

Delete task:

DELETE /api/scheduled-tasks/{id}

View executions:

GET /api/scheduled-tasks/{id}/executions

---

Best Practices

Naming Conventions

Use descriptive names that explain what the task does:

• ✅ Daily Sales Report - 9 AM
• ✅ Weekly Data Sync - Monday
• ❌ Task 1
• ❌ Test

Cron Scheduling

• Avoid overlapping executions - If a task takes 2 hours, don't schedule it every hour
• Consider time zones - Cron runs in server time (check your deployment)
• Use off-peak hours - Schedule heavy tasks during low-traffic times
• Test first - Run the team manually before automating it

Input Data

• Keep it minimal - Only pass what the team actually needs
• Use JSON - More structured than plain text
• Document the format - Add comments in the description
• Version your format - If you change the input structure, update all tasks

Error Handling

• Monitor execution history - Check for failures regularly
• Set up alerts - Use automations to notify on failures
• Have fallbacks - Don't rely on a single scheduled task for critical operations
• Log thoroughly - Ensure your team logs enough detail for debugging

---

Related Features

• Teams - Create and configure teams to run on schedule
• Automations - Trigger actions based on events
• Sessions - View results of scheduled executions