Custom Tasks Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Sections
- Settings Reference
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Are Custom Tasks?
Custom Tasks is a task scheduler module that manages execution of custom scripts. It allows scheduling scripts with cron profiles, setting execution parameters, tracking run history, and triggering manual execution.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Custom Tasks Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Custom Scripts │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ /opt/r2a/scripts/custom/ │ │
│ │ │ │
│ │ ├── daily-report.sh │ │
│ │ ├── sync-contacts.py │ │
│ │ ├── cleanup-temp.sh │ │
│ │ └── export-data.sh │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Referenced by tasks │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Custom Tasks │ │
│ │ │ │
│ │ Task: Daily Report │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Script: daily-report.sh │ │ │
│ │ │ Args: --format=pdf --email=admin@company.com │ │ │
│ │ │ Cron Profile: Daily Midnight │ │ │
│ │ │ Timeout: 300 seconds │ │ │
│ │ │ Run As: root │ │ │
│ │ │ Status: ● Enabled │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ │ Task: Contact Sync │ │
│ │ ┌────────────────────────────────────────────────────┐ │ │
│ │ │ Script: sync-contacts.py │ │ │
│ │ │ Cron Profile: Every 15 Min │ │ │
│ │ │ Status: ● Enabled │ │ │
│ │ └────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ Execution results │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Execution History │ │
│ │ │ │
│ │ Run 1: Jan 16 00:00 | Success | 12s | Exit: 0 │ │
│ │ Run 2: Jan 15 00:00 | Success | 14s | Exit: 0 │ │
│ │ Run 3: Jan 14 00:00 | Failed | 300s| Exit: 1 │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Tables
| Table | Purpose |
|---|
public.custom_tasks | Task configurations | |
public.custom_task_executions | Run history |
Key Files
| File | Description |
|---|
modules/customTasks/ | Frontend module | |
/opt/r2a/scripts/custom/ | Script location |
2. Module Overview (Commercial/Business)
Business Value
Custom Tasks provides automated script management:
| Without Module | With Module |
|---|
| Manual cron | Web interface | |
| No visibility | Execution tracking | |
| CLI only | GUI management | |
| No history | Run history |
Use Cases
- Automation
- Report generation
- Data synchronization
- Maintenance
- Cleanup scripts
- Health checks
- Integration
- API calls
- Data exports
- Monitoring
- Status checks
- Alert scripts
Feature Highlights
| Feature | Benefit |
|---|
| Script Selection | Dropdown from folder | |
| Cron Integration | Use Cron Profiles | |
| Arguments | Pass script params | |
| Timeout | Prevent runaway | |
| Run As User | Security control | |
| Execute Now | Manual trigger | |
| History | View past runs |
3. Module Overview (End User/Administrator)
What Can You Do?
- Create scheduled tasks
- Select scripts to run
- Set execution schedule
- Configure arguments
- Set timeout limits
- View execution history
- Run tasks manually
- Track success/failure
Custom Tasks - List View
┌─────────────────────────────────────────────────────────────────┐
│ Custom Tasks │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Manage scheduled custom script executions │
│ │
│ [+ Create Task] │
│ │
│ [🔍 Search tasks...] │
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Name │ Script │ Schedule │ Last Run│ St │ │
│ ├──────────────┼──────────────┼─────────────┼─────────┼────┤ │
│ │ Daily Report │ daily-report │ Daily │ Today │ ✓ │ │
│ │ Contact Sync │ sync-contacts│ Every 15min │ 10 min │ ✓ │ │
│ │ Cleanup Temp │ cleanup-temp │ Weekly │ Jan 14 │ ✓ │ │
│ │ Manual Task │ export-data │ Manual │ Never │ ● │ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Actions: [▶ Execute] [📋 History] [✏️ Edit] [🗑️ Delete] │
│ │
└─────────────────────────────────────────────────────────────────┘
Create/Edit Task
┌─────────────────────────────────────────────────────────────────┐
│ Create Custom Task │
├─────────────────────────────────────────────────────────────────┤
│ │
│ [General] [Execution] │
│ │
│ ▼ General Information │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Task Name: [Daily Report ] ││
│ │ ││
│ │ Description: [Generate and email daily stats ] ││
│ │ ││
│ │ Enabled: ✓ ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Script Configuration │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Script: [daily-report.sh ▼] ││
│ │ Scripts are located in /opt/r2a/scripts/custom/ ││
│ │ ││
│ │ Script Arguments: [--format=pdf --email=admin@co.com] ││
│ │ Optional arguments to pass to the script ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Schedule │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Cron Profile: [Daily Midnight ▼] ││
│ │ Leave empty for manual execution only ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ ▼ Execution Settings │
│ │
│ ┌─────────────────────────────────────────────────────────────┐│
│ │ ││
│ │ Timeout (seconds): [300 ] ││
│ │ Maximum execution time (1-86400 seconds) ││
│ │ ││
│ │ Run As User: [root ] ││
│ │ System user to run the script as ││
│ │ ││
│ └─────────────────────────────────────────────────────────────┘│
│ │
│ [Save] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────────┘
Execution History
┌─────────────────────────────────────────────────────────────────┐
│ Execution History - Daily Report │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────────────────────────────────────────────────────┐ │
│ │ Date/Time │ Trigger │ Duration│ Exit Code│ Status │ │
│ ├──────────────────┼─────────┼─────────┼──────────┼────────┤ │
│ │ Jan 16 00:00:15 │ Cron │ 12s │ 0 │ ✓ Success│ │
│ │ Jan 15 00:00:12 │ Cron │ 14s │ 0 │ ✓ Success│ │
│ │ Jan 15 14:30:00 │ Manual │ 8s │ 0 │ ✓ Success│ │
│ │ Jan 14 00:00:10 │ Cron │ 300s │ 1 │ ✗ Failed │ │
│ │ Jan 13 00:00:14 │ Cron │ 11s │ 0 │ ✓ Success│ │
│ └───────────────────────────────────────────────────────────┘ │
│ │
│ Click row to view output │
│ │
│ [Close] │
│ │
└─────────────────────────────────────────────────────────────────┘
Quick Tips
TIP
Script Location: Place scripts in
/opt/r2a/scripts/custom/
TIP
Manual Only: Leave Cron Profile empty for on-demand tasks.
WARNING
Timeout: Set appropriate timeout to prevent runaway scripts.
---
4. Configuration Sections
| Field | Description |
|---|
| Task Name | Task identifier | |
| Description | Task purpose | |
| Enabled | Active/Inactive |
Script Configuration
| Field | Description |
|---|
| Script | Script file to execute | |
| Script Arguments | Command line args |
Schedule
| Field | Description |
|---|
| Cron Profile | Schedule (or empty = manual) |
Execution Settings
| Field | Description |
|---|
| Timeout | Max run time (seconds) | |
| Run As User | Execution user |
5. Settings Reference
Execution Status
| Status | Description |
|---|
| Success | Exit code 0 | |
| Failed | Non-zero exit code | |
| Running | Currently executing | |
| Timeout | Exceeded time limit | |
| Killed | Manually stopped | |
| Never Run | Not yet executed |
Trigger Types
| Trigger | Description |
|---|
| Scheduled | Cron profile triggered | |
| Manual | Execute Now button | |
| API | API call triggered |
Timeout Values
| Value | Use Case |
|---|
| 60 | Quick scripts | |
| 300 | Standard (5 min) | |
| 3600 | Long-running (1 hr) | |
| 86400 | Very long (24 hr max) |
Common Script Types
| Type | Extension | Description |
|---|
| Bash | .sh | Shell scripts | |
| Python | .py | Python scripts | |
| Perl | .pl | Perl scripts | |
| Node | .js | Node.js scripts |
6. Common Scenarios & Examples
Scenario 1: Create Daily Report Task
- Click Create Task
- Name = "Daily Report"
- Script = daily-report.sh
- Args = "--format=pdf --email=admin@company.com"
- Cron Profile = Daily Midnight
- Timeout = 300
- Run As User = root
- Save
Scenario 2: Manual-Only Task
- Create Task
- Name = "Export Data"
- Script = export-data.sh
- Cron Profile = (leave empty)
- Save
- Execute Now when needed
Scenario 3: High-Frequency Sync
- Create Task
- Name = "CRM Sync"
- Script = sync-crm.py
- Cron Profile = Every 5 Minutes
- Timeout = 240 (allow time before next)
- Save
Scenario 4: Debug Failed Task
- Go to task list
- Click failed task
- Click View History
- Click failed execution
- View output and exit code
- Fix script issue
- Execute Now to verify
---
7. Limitations & Important Notes
Technical Notes
NOTE
Script Location: Scripts must be in
/opt/r2a/scripts/custom/
NOTE
Executable: Scripts must be executable (
chmod +x)
WARNING
Security: Run As User controls script permissions.
Best Practices
- Test Scripts: Test locally before adding
- Set Timeout: Prevent runaway processes
- Log Output: Scripts should output status
- Exit Codes: Use 0 for success, non-zero for failure
- Descriptive Names: Clear task naming
Script Requirements
| Requirement | Details |
|---|
| Location | /opt/r2a/scripts/custom/ | |
| Permissions | Executable (chmod +x) | |
| Shebang | Include #!/bin/bash or similar | |
| Exit Code | Return 0 for success | |
| Output | Stdout captured in history |
Example Script Template
#!/bin/bash
# Script: daily-report.sh
# Description: Generate daily report
set -e # Exit on error
echo "Starting daily report generation..."
# Your logic here
echo "Report generated successfully"
exit 0
---
8. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution |
|---|
| Script not listed | Not in folder | Move to custom folder | |
| Permission denied | Not executable | chmod +x script.sh | |
| Timeout | Script too slow | Increase timeout | |
| Failed status | Script error | Check output/exit code |
Check Script Status
# List available scripts
ls -la /opt/r2a/scripts/custom/
# Test script manually
sudo /opt/r2a/scripts/custom/daily-report.sh --arg
# Check permissions
ls -la /opt/r2a/scripts/custom/daily-report.sh
Debug Script
# Run with debug output
bash -x /opt/r2a/scripts/custom/script.sh
# Check exit code
/opt/r2a/scripts/custom/script.sh
echo $?
---
9. Glossary
| Term | Definition |
|---|
| Task | Scheduled script execution | |
| Script | Executable file | |
| Cron Profile | Schedule template | |
| Timeout | Max execution time | |
| Exit Code | Script return value | |
| Execution | Single run of task |
Lua Script Status ℹ️
Automation Module
| Component | Status |
|---|
| Custom Tasks | ℹ️ Script scheduler - no Lua handler required |
---
Documentation last updated: January 2026
