---
title: "Custom Tasks Module Documentation"
description: "Documentation for Custom Tasks"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [🎯 User Roles & Key Capabilities](#-user-roles--key-capabilities)
4. [Module Overview (Technical)](#1-module-overview-technical)
5. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
6. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
7. [Configuration Sections](#4-configuration-sections)
8. [Settings Reference](#5-settings-reference)
9. [Model Context Protocol (MCP) AI Integration](#model-context-protocol-mcp-ai-integration)
10. [Common Scenarios & Examples](#6-common-scenarios--examples)
11. [Limitations & Important Notes](#7-limitations--important-notes)
12. [Troubleshooting Tips](#8-troubleshooting-tips)
13. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Custom Tasks module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **Administration**.
3. Under **Maintenance**, click **Custom Tasks** (`/admin/maintenance/tasks`).
4. Review configured automation scripts, assigned cron profiles, timeout limits, execution users, and run state history.
5. Click **+ Add** to register a new automated or on-demand task script (`/admin/maintenance/tasks/new`), click the **Play** button on any task row to trigger an immediate ad-hoc execution, or inspect execution logs and exit codes.

---

## Screenshots & Visual Interface

### Custom Tasks Automation Registry
Central script automation directory displaying registered system maintenance jobs, assigned executable paths (`/opt/r2a/scripts/custom/`), cron profile links, timeout limits, target system user accounts, and status toggles.
![Custom Tasks Registry](/screenshots/admin/maintenance/custom-task-list.png)

### Custom Task Definition & Execution Parameters Form
Task configuration editor for naming the task, specifying target script paths, supplying optional runtime arguments, binding recurring cron execution profiles, configuring execution timeout caps (seconds), and assigning the target Linux user context.
![Create Custom Task Form](/screenshots/admin/maintenance/custom-task-form.png)

---

## 🎯 User Roles & Key Capabilities

| Role | Access Level | Responsibilities & Capabilities |
| :--- | :--- | :--- |
| **PBX Super Administrator** | Full Access (`RW`) | Register custom maintenance scripts (`/opt/r2a/scripts/custom/`), configure timeouts, assign execution Linux users, and trigger manual task runs. |
| **DevOps & Automation Engineer** | Script & Pipeline (`RW`) | Deploy bash, Python, PHP, or Lua automation scripts, link recurring cron profiles, and verify process exit codes. |
| **Platform Monitoring Lead** | Audit & Logs (`RO`) | Inspect task execution durations, review standard output/stderr traces, and detect hung or timed-out worker scripts. |
| **AI Platform Copilot / MCP Agent** | Programmatic Audit (`RO`) | Execute `list_custom_tasks` to check registered maintenance routines, last exit statuses, and run counts. |

---

## 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          │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **Automation**
   - Report generation
   - Data synchronization

2. **Maintenance**
   - Cleanup scripts
   - Health checks

3. **Integration**
   - API calls
   - Data exports

4. **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

### General Information

| 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 |

---

## Model Context Protocol (MCP) AI Integration

The Custom Tasks module connects to the **Model Context Protocol (MCP)**, allowing the Platform Copilot to audit registered administrative batch tasks, execution parameters, and historical exit codes.

### Available MCP Tools

| Tool Name | Scope | Description |
| :--- | :--- | :--- |
| `list_custom_tasks` | Task Registry (`RO`) | Lists custom maintenance scripts and batch tasks, showing execution intervals, run as user, timeout thresholds, and last exit status. |

### Tool Schemas & Payloads

#### `list_custom_tasks`
```json
{
  "name": "list_custom_tasks",
  "description": "Lists custom maintenance scripts and batch tasks, showing execution intervals, run as user, timeout thresholds, and last exit status.",
  "parameters": {
    "type": "object",
    "properties": {
      "search": {
        "type": "string",
        "description": "Filter by task name or script path."
      },
      "enabled": {
        "type": "boolean",
        "description": "Filter by active/enabled status."
      }
    }
  }
}
```

**Realistic Execution Response:**
```json
{
  "success": true,
  "data": {
    "total": 2,
    "tasks": [
      {
        "id": 1,
        "name": "Nightly CDR Partition Sync",
        "description": "Aggregates and syncs daily CDR partition tables to the reporting archive",
        "scriptPath": "/opt/r2a/scripts/custom/sync_cdr_partitions.sh",
        "scriptArgs": "--compress --verbose",
        "runAsUser": "softswitch",
        "timeoutSeconds": 300,
        "enabled": true,
        "cronProfile": "Nightly Database Backup (0 2 * * *)",
        "lastRun": "2026-09-08T02:00:01Z",
        "lastStatus": "success",
        "lastExitCode": 0,
        "runCount": 142
      },
      {
        "id": 2,
        "name": "Temporary Audio Files Purge",
        "description": "Scans and removes stale TTS cache files older than 48 hours",
        "scriptPath": "/opt/r2a/scripts/custom/purge_tts_cache.py",
        "scriptArgs": null,
        "runAsUser": "softswitch",
        "timeoutSeconds": 120,
        "enabled": true,
        "cronProfile": "Weekly Cleanup Routine (0 3 * * 0)",
        "lastRun": "2026-09-06T03:00:00Z",
        "lastStatus": "success",
        "lastExitCode": 0,
        "runCount": 24
      }
    ]
  }
}
```

### Bilingual Natural Language Prompt Examples

#### English Prompts
- *"Copilot, list all configured custom maintenance tasks and their current execution status."*
- *"Did the nightly CDR partition sync script exit with code 0 on its last run?"*
- *"Show me any custom tasks that are currently disabled or failed on their last execution."*

#### Spanish Prompts
- *"Copilot, lista todas las tareas personalizadas configuradas y su último estado de ejecución."*
- *"¿Cuál fue el código de salida (exit code) del script de sincronización de CDRs?"*
- *"Verifica qué scripts de mantenimiento están habilitados y bajo qué usuario se ejecutan."*

### Enterprise Safeguards & Execution Boundaries
1. **Restricted Script Path Sandbox:** Scripts must reside within authorized directories (`/opt/r2a/scripts/custom/` or `/var/www/softswitch/scripts/custom/`) and match allowed extensions (`.sh`, `.py`, `.php`, `.lua`). Arbitrary system binary execution is strictly prevented.
2. **Tenant Boundary Isolation:** Custom tasks are isolated by `tenant_id`. Sub-tenants cannot inspect or execute tasks configured by the main platform tenant.
3. **Execution Timeout Caps:** Every task enforces a mandatory timeout limit (maximum 86400 seconds) to terminate hanging processes and prevent thread pool starvation.

---

## 6. Common Scenarios & Examples

### Scenario 1: Create Daily Report Task

1. Click Create Task
2. Name = "Daily Report"
3. Script = daily-report.sh
4. Args = "--format=pdf --email=admin@company.com"
5. Cron Profile = Daily Midnight
6. Timeout = 300
7. Run As User = root
8. Save

### Scenario 2: Manual-Only Task

1. Create Task
2. Name = "Export Data"
3. Script = export-data.sh
4. Cron Profile = (leave empty)
5. Save
6. Execute Now when needed

### Scenario 3: High-Frequency Sync

1. Create Task
2. Name = "CRM Sync"
3. Script = sync-crm.py
4. Cron Profile = Every 5 Minutes
5. Timeout = 240 (allow time before next)
6. Save

### Scenario 4: Debug Failed Task

1. Go to task list
2. Click failed task
3. Click View History
4. Click failed execution
5. View output and exit code
6. Fix script issue
7. 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

1. **Test Scripts**: Test locally before adding
2. **Set Timeout**: Prevent runaway processes
3. **Log Output**: Scripts should output status
4. **Exit Codes**: Use 0 for success, non-zero for failure
5. **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

```bash
#!/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

```bash
# 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

```bash
# 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 |

---

*Documentation last updated: January 2026*