Back to Help | Back to login

JOBS AND COMMANDS DOCUMENTATION

Central Business Platform (CBP)

Back to Help FAQs User Guide Approvers Guide
Access: The CBP platform is available at https://cbp.africacdc.org/staff/apm. You must have a valid account to sign in.
No matching content found. Try different keywords.

Africa CDC APM - Jobs and Commands Documentation

This document provides a comprehensive overview of all jobs, commands, and scheduled tasks in the Africa CDC Approvals Management System.

📋 Table of Contents

  1. Background Jobs
  2. Console Commands
  3. Scheduled Tasks
  4. Job Management Script
  5. System Health Monitoring
  6. Troubleshooting

🔄 Background Jobs

Email BCC Configuration

  • All emails sent by the system are automatically BCC'd to system@africacdc.org
  • This includes notifications, reminders, test emails, and matrix notifications
  • The BCC is handled at the Exchange service level for consistency

Core Notification Jobs

1. `SendDailyPendingApprovalsNotificationJob`

  • Purpose: Sends daily pending approvals notifications to all approvers
  • Queue: default
  • Tries: 3
  • Timeout: 300 seconds (5 minutes)
  • Schedule: Daily at 9:00 AM, 4:00 PM, and 1:07 AM (GMT+3)
  • Dependencies: NotificationService, PendingApprovalsService

2. `SendNotificationEmailJob`

  • Purpose: Sends individual email notifications using Exchange service
  • Queue: default
  • Tries: 3
  • Timeout: 120 seconds
  • BCC: All emails are BCC'd to system@africacdc.org
  • Dependencies: Exchange OAuth service, email templates

3. `SendMatrixNotificationJob`

  • Purpose: Sends matrix approval notifications
  • Queue: default
  • Tries: 3
  • Timeout: 60 seconds
  • Dependencies: Exchange OAuth service, matrix templates

Document Management Jobs

4. `AssignDocumentNumberJob`

  • Purpose: Assigns document numbers to new records
  • Queue: default
  • Tries: 3
  • Timeout: 60 seconds
  • Dependencies: Document numbering system

5. `ResetDocumentCountersJob`

  • Purpose: Resets document counters for specific periods
  • Queue: default
  • Tries: 3
  • Timeout: 60 seconds

Maintenance Jobs

6. `ArchiveOldApprovalTrailsJob`

  • Purpose: Archives old approval trails to maintain database performance
  • Queue: default
  • Tries: 3
  • Timeout: 300 seconds

🖥️ Console Commands

Job Management Commands

`jobs:test-daily-notifications`

  • Purpose: Test daily pending approvals notifications without sending emails
  • Usage: php artisan jobs:test-daily-notifications
  • Output: Shows which approvers would receive notifications and how many pending items they have

`jobs:dispatch-daily-notifications`

  • Purpose: Manually dispatch daily pending approvals notification job
  • Usage: php artisan jobs:dispatch-daily-notifications
  • Output: Dispatches job to queue for processing

`jobs:process-queue`

  • Purpose: Process one job from the queue
  • Usage: php artisan jobs:process-queue
  • Output: Processes and displays job execution details

`jobs:monitor-queue`

  • Purpose: Monitor and process queue jobs
  • Usage: php artisan jobs:monitor-queue
  • Output: Shows queue status and processes jobs if available

Notification Commands

`reminders:schedule`

  • Purpose: Schedule instant reminders to all approvers with pending items
  • Usage: php artisan reminders:schedule [--test] [--force]
  • Options:

- --test: Run in test mode (dry run)

- --force: Force run even if not scheduled time

  • Schedule: Daily at 9:00 AM and 4:00 PM (GMT+3)
  • Creates Jobs: Dispatches SendDailyPendingApprovalsNotificationJob to create individual notification jobs

`notifications:send-test {staff_id}`

  • Purpose: Send test pending approvals notification to specific staff member
  • Usage: php artisan notifications:send-test 558
  • Output: Sends personalized notification to specified staff member
  • BCC: All test emails are BCC'd to system@africacdc.org

`reminders:send-instant`

  • Purpose: Send instant pending approval reminders to staff members
  • Usage:

- php artisan reminders:send-instant --staff-id=558 (specific staff by ID)

- php artisan reminders:send-instant --email=user@example.com (specific staff by email)

- php artisan reminders:send-instant --all (all approvers with pending items)

- php artisan reminders:send-instant --test (dry run mode)

- php artisan reminders:send-instant --force (force send even if no pending items)

  • Output: Sends instant reminders with pending items breakdown
  • BCC: All reminder emails are BCC'd to system@africacdc.org

`notifications:test-email`

  • Purpose: Test email notification system
  • Usage: php artisan notifications:test-email
  • Output: Tests email configuration and delivery

`notifications:test-all`

  • Purpose: Test all notification systems
  • Usage: php artisan notifications:test-all
  • Output: Comprehensive notification system test

Document Management Commands

`assign:document-numbers`

  • Purpose: Assign document numbers to existing records that don't have them
  • Usage: php artisan assign:document-numbers
  • Output: Processes records and assigns missing document numbers

`assign:missing-document-numbers`

  • Purpose: Assign document numbers to records that are missing them
  • Usage: php artisan assign:missing-document-numbers
  • Output: Identifies and assigns missing document numbers

`document:reset-counters`

  • Purpose: Reset document counters for a specific year, division, or document type
  • Usage: php artisan document:reset-counters
  • Output: Resets document numbering counters

`fix:document-conflicts`

  • Purpose: Fix document number conflicts and reset counters after deletions
  • Usage: php artisan fix:document-conflicts
  • Output: Resolves document number conflicts

`monitor:document-jobs`

  • Purpose: Monitor document number assignment jobs
  • Usage: php artisan monitor:document-jobs
  • Output: Shows status of document assignment jobs

`monitor:document-numbers`

  • Purpose: Monitor and automatically assign document numbers to records that need them
  • Usage: php artisan monitor:document-numbers
  • Output: Monitors and assigns document numbers automatically

Data Synchronization Commands

`directorates:sync`

  • Purpose: Synchronize directorates data
  • Usage: php artisan directorates:sync
  • Schedule: Daily at 6:00 AM and 11:00 PM (GMT+3)

`divisions:sync`

  • Purpose: Synchronize divisions data
  • Usage: php artisan divisions:sync
  • Schedule: Daily at 6:05 AM and 11:05 PM (GMT+3)

`staff:sync`

  • Purpose: Synchronize staff data
  • Usage: php artisan staff:sync
  • Schedule: Daily at 6:10 AM and 11:10 PM (GMT+3)

Approval Management Commands

`approval:archive-trails`

  • Purpose: Archive old approval trails for matrices and activities
  • Usage: php artisan approval:archive-trails
  • Output: Archives old approval trails to maintain performance

`approval:manage-trails`

  • Purpose: Manage approval trails - show statistics, archive old trails, or cleanup
  • Usage: php artisan approval:manage-trails
  • Output: Provides approval trail management options

`apm:fix-single-memo-promoted-approval-trails`

  • Purpose: One-time / maintenance fix for activities already converted from a matrix memo to a single memo. It realigns rows in approval_trails (morph Activity) with the source activity_approval_trails after promotion.
  • When to use: Historical data where promoted trails still store matrix-style actions (passed, convert_to_single_memo, converted_to_single_memo) instead of single-memo workflow actions (approved, returned), or where created_at / updated_at were lost on copy.
  • What it does (for each is_single_memo activity, pairing the first N rows by id order, N = min(activity trails, approval trails)):

- Sets approval_trails.action using the same mapping as live conversion: passed → approved; convert_to_single_memo / converted_to_single_memo → returned; other actions unchanged.

- Copies created_at and updated_at from the paired activity_approval_trails row.

- Ensures the returned row (from convert-to-single-memo) has a timestamp strictly after every other paired row so it appears first when sorting trails by created_at descending (last action on top).

  • Caveat: Pairing assumes promoted approval_trails were inserted before any later single-memo workflow rows, in the same order as activity_approval_trails. If counts differ, only the first N pairs are updated; review with --dry-run.
  • Usage (run from the apm/ directory):

- php artisan apm:fix-single-memo-promoted-approval-trails --dry-run — report changes only

- php artisan apm:fix-single-memo-promoted-approval-trails — apply fixes

- php artisan apm:fix-single-memo-promoted-approval-trails --activity-id=118 — limit to one activity (optional with --dry-run)

  • Options:

- --dry-run — no database writes

- --activity-id= — process only that activity ID

  • Related code: ActivityApprovalTrail::mapActionForPromotionToApprovalTrail(), ActivityApprovalTrail::createPromotedApprovalTrail() (new conversions preserve source timestamps automatically).

System Health Commands

`system:health-check`

  • Purpose: Check system health and configuration
  • Usage: php artisan system:health-check
  • Output: Comprehensive system health report including:

- Database connectivity

- Queue tables status

- Storage permissions

- Log file availability

Queue Management Commands

`queue:clear-failed`

  • Purpose: Clear all failed jobs from the queue
  • Usage: php artisan queue:clear-failed
  • Output: Removes all failed jobs from the queue

`queue:retry-failed`

  • Purpose: Retry all failed jobs
  • Usage: php artisan queue:retry-failed
  • Output: Retries all failed jobs in the queue

⏰ Scheduled Tasks

Scheduler Configuration

  • Configuration File: app/Providers/ScheduleServiceProvider.php
  • Timezone: Africa/Addis_Ababa (GMT+3)
  • Execution: php artisan schedule:work (continuous) or php artisan schedule:run (one-time)
  • Service: Managed via laravel-scheduler.service systemd service

Daily Data Synchronization

  • 6:00 AM GMT+3: directorates:sync
  • 6:05 AM GMT+3: divisions:sync
  • 6:10 AM GMT+3: staff:sync

Evening Data Synchronization

  • 11:00 PM GMT+3: directorates:sync
  • 11:05 PM GMT+3: divisions:sync
  • 11:10 PM GMT+3: staff:sync

Daily Notifications

  • 9:00 AM GMT+3: reminders:schedule (Morning reminders)
  • 4:00 PM GMT+3: reminders:schedule (Evening reminders)

Note: Scheduled tasks are configured in app/Providers/ScheduleServiceProvider.php and run automatically via php artisan schedule:work.

🛠️ Job Management Script

The manage-jobs.sh script provides easy management of all jobs and services:

Available Commands

# System Status
./manage-jobs.sh status              # Show system and queue status
./manage-jobs.sh health              # Run comprehensive health check

# Notification Management
./manage-jobs.sh test-notifications  # Test notification system (dry run)
./manage-jobs.sh send-test <staff_id> # Send test notification to specific staff
./manage-jobs.sh send-reminder <staff_id> # Send instant reminder to specific staff
./manage-jobs.sh send-reminder-email <email> # Send instant reminder to specific email
./manage-jobs.sh send-reminder-all   # Send instant reminders to all approvers
./manage-jobs.sh schedule-reminders  # Schedule instant reminders for all approvers
./manage-jobs.sh dispatch-daily      # Dispatch daily pending approvals job

# Queue Management
./manage-jobs.sh process-queue       # Process one job from the queue
./manage-jobs.sh monitor-queue       # Monitor and process queue jobs
./manage-jobs.sh clear-failed        # Clear all failed jobs
./manage-jobs.sh retry-failed        # Retry all failed jobs

# Service Management
./manage-jobs.sh start-worker        # Start queue worker (background)
./manage-jobs.sh stop-worker         # Stop queue worker
./manage-jobs.sh restart-worker      # Restart queue worker
./manage-jobs.sh start-scheduler     # Start scheduler (background)
./manage-jobs.sh stop-scheduler      # Stop scheduler
./manage-jobs.sh restart-scheduler   # Restart scheduler

# Logs and Monitoring
./manage-jobs.sh logs                # Show recent job logs

📊 System Health Monitoring

Health Check Components

The system:health-check command verifies:

  1. Database Connectivity

- Connection to MySQL database

- Query execution capability

  1. Queue System

- jobs table existence and accessibility

- failed_jobs table existence and accessibility

- Current queue status (pending/failed jobs count)

  1. Storage System

- Storage directory writability

- Log file accessibility

  1. Logging System

- Laravel log file existence

- Log file readability

Monitoring Commands

# Quick status check
./manage-jobs.sh status

# Comprehensive health check
./manage-jobs.sh health

# Queue monitoring
./manage-jobs.sh monitor-queue

# View logs
./manage-jobs.sh logs

🔧 Troubleshooting

Common Issues

1. Jobs Not Processing

# Check queue status
./manage-jobs.sh monitor-queue

# Restart queue worker
./manage-jobs.sh restart-worker

# Check failed jobs
php artisan queue:failed

2. Notifications Not Sending

# Test notification system
./manage-jobs.sh test-notifications

# Send test to specific user
./manage-jobs.sh send-test 558

# Check Exchange configuration
php artisan system:health-check

3. Document Numbers Not Assigning

# Monitor document jobs
php artisan monitor:document-jobs

# Assign missing document numbers
php artisan assign:missing-document-numbers

# Fix document conflicts
php artisan fix:document-conflicts

4. Scheduled Tasks Not Running

# Check scheduler status
./manage-jobs.sh status

# Restart scheduler
./manage-jobs.sh restart-scheduler

# Test scheduled commands manually
php artisan reminders:schedule --test

Log Files

  • Main Log: storage/logs/laravel.log
  • Job Management Log: storage/logs/job-management.log
  • Daily Logs: storage/logs/laravel-YYYY-MM-DD.log

Service Management

Queue Worker Service

  • Service File: laravel-queue-apm.service
  • Status: systemctl status laravel-queue-apm
  • Start: systemctl start laravel-queue-apm
  • Stop: systemctl stop laravel-queue-apm

Scheduler Service

  • Service File: laravel-scheduler.service
  • Status: systemctl status laravel-scheduler
  • Start: systemctl start laravel-scheduler
  • Stop: systemctl stop laravel-scheduler

📈 Performance Monitoring

Queue Metrics

  • Pending Jobs: php artisan queue:monitor
  • Failed Jobs: php artisan queue:failed
  • Job Processing Rate: Monitor logs for processing times

Notification Metrics

  • Daily Notifications Sent: Check logs for notification counts
  • Email Delivery Success Rate: Monitor Exchange service logs
  • Approver Coverage: Test command shows which approvers have pending items

System Resources

  • Memory Usage: Monitor queue worker memory consumption
  • Database Performance: Check query execution times
  • Storage Usage: Monitor log file sizes and cleanup needs

🚀 Quick Start Guide

1. Start All Services

./manage-jobs.sh start-scheduler
./manage-jobs.sh start-worker

2. Verify System Health

./manage-jobs.sh health

3. Test Notifications

./manage-jobs.sh test-notifications
./manage-jobs.sh send-test 558

4. Monitor System

./manage-jobs.sh status
./manage-jobs.sh logs

📞 Support

For issues or questions regarding jobs and commands:

  1. Check system health: ./manage-jobs.sh health
  2. Review logs: ./manage-jobs.sh logs
  3. Test specific functionality using the test commands
  4. Check service status using systemctl commands

Last updated: March 30, 2026

Version: 1.1

Last Updated: April 2026 Back to Help Center
Help Center Back to login