# Required cron jobs

Cron jobs must be configured on the server for the DOI Gov API. Run from the project root or ensure `php` is in PATH.

**Environment status:** Update per cron — `DEV[PENDING]` / `DEV[DONE]`, `QA[PENDING]` / `QA[DONE]` (PENDING = not configured in that env, DONE = configured).

---

## 1. Email queue worker

**Environments:** DEV[PENDING] QA[PENDING]

**Purpose:** Processes pending rows in `tbl_email_queue` and sends emails. Each run claims a batch so concurrent runs don’t process the same rows. Rows stuck in `processing` longer than the timeout are reset to `pending`.

**Schedule:** Every 5 minute  
**Cron expression:** `5 * * * *`

**Command:**
```bash
php /var/www/doi_gov_api/cli/email_queue_worker.php
```

**Example crontab entry:**
```
5 * * * * php /var/www/doi_gov_api/cli/email_queue_worker.php
```

**Requirements:**
- Table `tbl_email_queue` with locking columns (`locked_at`, `locked_by`)

**Script:** `cli/email_queue_worker.php`

---

## 1b. Email queue purge worker

**Environments:** DEV[PENDING] QA[PENDING]

**Purpose:** Deletes old `sent` / `dead_letter` rows from `tbl_email_queue` and old rows from `tbl_email_history` per `email_queue_retention_days` and `email_history_retention_days` in `tbl_platform_config`. Requires `incremental_email_queue_payload.sql`.

**Schedule:** Once daily at 02:00  
**Cron expression:** `0 2 * * *`

**Command:**
```bash
php /var/www/doi_gov_api/cli/email_queue_purge_worker.php
```

**Example crontab entry:**
```
0 2 * * * php /var/www/doi_gov_api/cli/email_queue_purge_worker.php
```

**Script:** `cli/email_queue_purge_worker.php`

---

## 2. Evaluation status worker

**Environments:** DEV[PENDING] QA[PENDING]

**Purpose:** Updates evaluation status for projects and evaluators: marks projects past due as overdue and sets evaluator rows to `overdue`. Does **not** queue emails directly — reminder emails are sent via separate evaluation reminder API/cron paths that call `mailToQueue()`.

**Schedule:** Once daily at midnight (00:00)  
**Cron expression:** `0 0 * * *`

**Command:**
```bash
php /var/www/doi_gov_api/cli/evaluation_status_worker.php
```

**Example crontab entry:**
```
0 0 * * * php /var/www/doi_gov_api/cli/evaluation_status_worker.php
```

**Requirements:**
- Database access; evaluation reminder emails use `EvaluationReminderEmailService` + `mailToQueue()` (email queue worker sends them).

**Script:** `cli/evaluation_status_worker.php`

---

## 2b. Calendar event reminder worker

**Environments:** DEV[PENDING] QA[PENDING]

**Purpose:** Sends calendar event in-app and email reminders; email jobs are queued via `mailToQueue()` with `template_key = calendar_event_reminder`.

**Schedule:** Every 5 minutes (example)  
**Cron expression:** `*/5 * * * *`

**Command:**
```bash
php /var/www/doi_gov_api/cli/calendar_event_reminder_worker.php
```

**Script:** `cli/calendar_event_reminder_worker.php`

---

## 3. Database backup

**Environments:** DEV[DONE] QA[PENDING]

**Purpose:** Daily backup of the database. Backups are stored in an environment-specific directory; the script auto-deletes backups older than 7 days.

**Schedule:** Once daily at midnight (00:00)  
**Cron expression:** `0 0 * * *`

**Backup locations (by environment):**
- **DEV:** `/home/ubuntu/dev_db_backups`
- **QA:** `/home/ubuntu/qa_db_backups`

**Script location:** `/home/ubuntu/DEV_DB_backup_shell_script.sh` (run from `/home/ubuntu`)

**Command (from `/home/ubuntu`):**
```bash
cd /home/ubuntu
./DEV_DB_backup_shell_script.sh
```

**Example crontab entry:**
```
0 0 * * * /bin/bash /home/ubuntu/DEV_DB_backup_shell_script.sh >> /home/ubuntu/backup_log.txt 2>&1
```

**Notes:**
- Not part of the API repo (no CLI); script lives on the server at `/home/ubuntu/`.
- Logs append to `/home/ubuntu/backup_log.txt`.
- Backups older than 7 days are automatically deleted by the script.

---

## Summary

| Job                     | Schedule      | Script / command                                      | DEV       | QA       |
|-------------------------|---------------|--------------------------------------------------------|-----------|----------|
| Email queue worker      | Every 5 min   | `cli/email_queue_worker.php`                           | PENDING   | PENDING  |
| Email queue purge       | Daily 02:00   | `cli/email_queue_purge_worker.php`                     | PENDING   | PENDING  |
| Calendar reminder worker| Every 5 min   | `cli/calendar_event_reminder_worker.php`               | PENDING   | PENDING  |
| Evaluation status worker| Daily 00:00   | `cli/evaluation_status_worker.php`                     | PENDING   | PENDING  |
| Database backup         | Daily 00:00   | `/home/ubuntu/DEV_DB_backup_shell_script.sh` (server)  | DONE      | PENDING  |

**Note:** Use the same PHP binary and user that the web app uses for the CLI workers. Ensure `app_config.php` and DB credentials are correct for the CLI environment. The database backup script is maintained on the server and is not in the API codebase.