Indicator System Submissions

Overview

The Indicator System Submissions feature is an automated process that generates compliance indicator submissions for system-managed metrics. Unlike manual submissions that require user input, this system automatically calculates and submits indicator data based on existing platform data such as programme element completion progress and session attendance records.

The core component is the SubmitSystemComplianceIndicators Artisan command, which runs on a monthly scheduled basis (on the last day of the month) to process system-type compliance indicators that are due for submission. This automation ensures that compliance reporting remains current without requiring manual intervention from entrepreneurs or administrators.

System Purpose

The system addresses the need to automatically track and report on measurable compliance metrics that can be derived from existing platform data. This automation:

Reduces administrative burden by eliminating manual data entry for calculable metrics
Ensures data accuracy by using authoritative platform data sources
Maintains compliance timeliness through automated month end processing
Provides audit trails through comprehensive logging and notifications
Ensure point in time data by submitting data at the end of the month as it is at that point in time

Architecture Integration

The system integrates with the broader indicator ecosystem through:

Task Management: Leverages existing indicator task lifecycle
Submission Pipeline: Uses standard submission creation and verification flows
Event System: Dispatches events for submission lifecycle integration
Dashboard Integration: Automatically updates entrepreneur dashboards
Audit Trail: Maintains complete history of automated submissions

This automated approach ensures that system-calculable compliance metrics are consistently tracked and reported without manual intervention, while maintaining the same data integrity and audit capabilities as manual submissions.

Command Execution

When It Runs

The command is typically scheduled to run on the last day of the month at 23:45, processing tasks that are due on the current date.

It only submits indicator tasks that are due on the current date, this is to ensure that the data submitted matches the due date of the task, ensuring accurate reporting. The command does not ever go retrospectively and submit data for tasks that are due in the past, or update data for prior submissions as this would make the data inaccurate.

Command Signature:

php artisan indicators:submit-system-compliance-indicators {--tenant=1}

Task Selection Criteria

The command processes indicator tasks that meet all of the following criteria:

System Responsibility: responsible_type = 'system' (note this is set based on the type of Compliance Indicator)
Due Date: due_date equals today's date
Submittable Status: Task status must be one of:
- PENDING
- NEEDS_REVISION
- OVERDUE
No Existing Submission: The task must not already have a submission

Processing Flow

For each qualifying task, the command:

Validates the task - Ensures it doesn't already have a submission and is in a submittable status
Determines compliance type - Identifies which type of system metric to calculate
Gathers data - Uses appropriate services to calculate current values
Creates submission - Generates an auto-approved submission with calculated data
Logs results - Records success or failure with detailed context

Supported Compliance Types

The system currently processes three types of system compliance indicators:

Element Progress (`element-progress`)

Tracks completion progress across programme elements for an entrepreneur.

Data Source: ProgrammeElementProgressCalculationService
Metric: Percentage of completed fields across all programme elements
Comment Format: "Completed X of Y total fields in programme elements"
Achievement Logic: Percentage >= target value

Learning Attendance (`attendance-learning`)

Monitors attendance at learning sessions within the programme.

Data Source: ProgrammeSessionAttendanceService
Metric: Percentage attendance at learning category sessions
Comment Format: JSON metadata including attendance details
Achievement Logic: Percentage >= target value

Mentoring Attendance (`attendance-mentoring`)

Tracks attendance at mentoring sessions within the programme.

Data Source: ProgrammeSessionAttendanceService
Metric: Percentage attendance at mentoring category sessions
Comment Format: JSON metadata including attendance details
Achievement Logic: Percentage >= target value

Submission Behavior

When Submissions Are Created

Submissions are created for all qualifying tasks, regardless of whether the target is achieved. This ensures complete audit trails and allows tracking of both successful and unsuccessful compliance periods.

When Submissions Are Skipped

The command will skip processing and log the reason when:

Task already has submission: Prevents duplicate submissions for the same task
Task not submittable: Status is COMPLETED or SUBMITTED
Invalid compliance type: Task references a compliance type not supported for system submission (e.g., OTHER)
Service errors: Data calculation services encounter errors or missing data

Auto-Approval Process

All system-generated submissions are automatically set to APPROVED status because:

Data integrity: Values are calculated from authoritative platform sources
No verification needed: System tasks bypass the normal verification workflow
Immediate completion: Tasks transition directly to COMPLETED status

Logging and Monitoring

Log Channel

All activity is logged to the indicators channel with structured context:

Log::channel('indicators')->info('SubmitSystemComplianceIndicators: Message', $context);

Log Messages

Informational:

Process start/completion
Task skipping with reasons
Successful submission creation

Critical Errors:

Submission creation failures
Invalid compliance types
Service calculation errors

Slack Notifications

Critical errors trigger Slack alerts to the configured default channel, providing immediate notification of system issues that require attention.

Console Output

The command provides real-time feedback during execution:

Progress messages for each task processed
Skip notifications with reasons
Error messages for failed submissions

Service Dependencies

The command relies on several key services and factories:

IndicatorSubmissionService

Handles the creation and persistence of indicator submissions, including:

Database transaction management
Event dispatching for submission lifecycle
Dashboard cache invalidation
Status and achievement determination

ProgrammeElementProgressCalculationServiceFactory

Creates service instances for calculating programme element completion:

Input: Entrepreneur, Organisation, Programme context
Output: Consolidated progress data with completion percentages
Scope: All programme elements assigned to the entrepreneur

ProgrammeSessionAttendanceServiceFactory

Creates service instances for calculating session attendance:

Input: Organisation Programme Seat context
Output: Attendance statistics with metadata
Scope: Learning or mentoring sessions based on category type

Error Handling

Exception Management

The command implements comprehensive error handling:

Individual task failures don't stop processing of remaining tasks
Detailed error logging captures exception messages and context
Graceful degradation allows partial success scenarios
Alert mechanisms notify administrators of critical issues

Common Failure Scenarios

Invalid Compliance Types:

Thrown when a task references an unsupported compliance type
Results in InvalidComplianceTypeForSystemSubmissionException
Task is skipped and error is logged

Service Calculation Errors:

Network issues, missing data, or service unavailability
Logged as critical errors with full exception context
Slack notifications sent for immediate attention

Database Transaction Failures:

Submission creation or related data persistence issues
Full transaction rollback ensures data consistency
Detailed logging for debugging and resolution