← Back to Awards Plugin

5.2.6 AwardsTablePolicy Reference

Last Updated: December 4, 2025
Status: Complete
Plugin: Awards
Source: plugins/Awards/src/Policy/AwardsTablePolicy.php

Overview

The AwardsTablePolicy class provides table-level authorization for Awards data operations, implementing query scoping, bulk operation authorization, and approval level filtering based on user permissions. It integrates with the Awards recommendation system for fine-grained access control.

Class Definition

namespace Awards\Policy;

class AwardsTablePolicy extends BasePolicy

Table-Level Authorization Architecture

Query Scoping

• Branch Integration: Awards access controlled through branch-based scoping
• Approval Level Filtering: Awards filtered by approval levels user has authority to manage
• Permission Integration: Seamless integration with PermissionsLoader and warrant-based authorization

Inherited Methods

Standard operations inherited from BasePolicy:

Method	Purpose
canAdd()	Award creation authorization
canIndex()	Awards listing authorization
canExport()	Awards export authorization

Methods

scopeIndex

Applies query scoping for Awards index operations based on user permissions and approval authority.

public function scopeIndex(KmpIdentityInterface $user, $query): SelectQuery

Parameters:

• $user - The authenticated user requesting access
• $query - The Awards table query to be scoped

Returns: Scoped query with branch and level filtering applied.

Scoping Logic:

1. Branch Permission Discovery: User’s branch permissions resolved through _getBranchIdsForPolicy()
2. Policy Analysis: User policies analyzed to discover recommendation approval authority
3. Level Extraction: Award levels extracted from canApproveLevel* permission methods
4. Query Filtering: Awards filtered by authorized branches and approval levels

scopeGridData

Provides query scoping for Dataverse grid data endpoint.

public function scopeGridData(KmpIdentityInterface $user, mixed $query): mixed

Delegates to scopeIndex() for consistent authorization behavior.

Query Scoping Implementation

Branch-Based Filtering

Awards access controlled through organizational hierarchy:

• Branch permissions discovered via BasePolicy._getBranchIdsForPolicy()
• AwardsTable.addBranchScopeQuery() applied for organizational data isolation
• Empty branch list allows global access for administrative users
• Multi-branch support for complex organizational structures

Approval Level Filtering

Awards filtered based on recommendation approval authority:

• User policies analyzed for RecommendationPolicy permissions
• Methods starting with canApproveLevel parsed to extract level names
• Awards filtered to show only those at levels user can approve
• Levels association contained for efficient filtering

Usage Examples

Controller Integration

// AwardsController index with automatic query scoping
public function index() {
    $query = $this->Awards->find();
    $query = $this->Authorization->applyScope($query); // Uses scopeIndex()
    $awards = $this->paginate($query);
    $this->set(compact('awards'));
}

Service Layer Integration

// Award discovery service with policy scoping
public function getAuthorizedAwards($filters = []) {
    $query = $this->Awards->find()
        ->where($filters);
    
    // Automatic scoping based on user permissions
    $query = $this->Authorization->applyScope($query);
    return $query->toArray();
}

Administrative Operations

// Administrative award management with scoping
public function generateAwardReport($branchId = null) {
    $query = $this->Awards->find()
        ->contain(['Domains', 'Levels', 'Recommendations']);
    
    if ($branchId) {
        $query = $query->where(['Awards.branch_id' => $branchId]);
    }
    
    // Policy automatically filters to authorized awards
    $query = $this->Authorization->applyScope($query);
    return $query->toArray();
}

Approval Authority Filtering

// Awards filtered by approval authority for workflow optimization
public function getManageableAwards() {
    $query = $this->Awards->find()
        ->contain(['Levels', 'Domains']);
    
    // Policy automatically filters to awards at levels user can approve
    $query = $this->Authorization->applyScope($query);
    return $query->toArray();
}

Integration Points

BasePolicy Integration

• Standard Operations: Inherits authorization through delegation
• Permission Framework: Seamless integration with RBAC
• Branch Scoping: Organizational access control
• Administrative Authority: Super user permissions for system management

PermissionsLoader Integration

• Permission Discovery: Award table permissions resolved through centralized loading
• Warrant Integration: Table operations authorized through warrant-based validation
• Branch Authorization: Multi-branch permission resolution
• Caching Support: Permission data cached for performance

Recommendation System Integration

• Approval Authority: Award filtering based on recommendation approval authority
• Level Integration: Awards filtered by levels user has authority to approve
• Policy Coordination: Integration between Awards and Recommendations policies
• Workflow Optimization: Award access optimized for recommendation workflow

Security Considerations

Data Protection

• Branch Isolation: Award data access limited to authorized organizational contexts
• Permission Validation: All table operations validated against RBAC permissions
• Query Security: Queries protected through ORM integration
• Audit Trail: Table operations logged for compliance monitoring

Performance Considerations

• Query Optimization: Scoping implemented at database level
• Permission Caching: User permissions cached to reduce overhead
• Index Utilization: Query scoping designed to use database indexes
• Scalability: Authorization system scales with organizational growth

Related Documentation

• Awards Plugin Overview
• Award Policy Reference
• RBAC Security Architecture
• Dataverse Grid System