5.2.17 Awards Services
The Awards plugin deliberately uses focused services instead of one large recommendation manager. This map describes ownership; exact APIs live under app/plugins/Awards/src/Services and in generated documentation.
Recommendation services
| Responsibility | Services |
|---|---|
| Create/edit/delete | RecommendationSubmissionService, RecommendationUpdateService, RecommendationDeletionService, form/query support |
| State and audit | RecommendationTransitionService, RecommendationStateLogService, bestowal-state policy |
| Grouping | RecommendationGroupingService |
| Approval configuration/execution | RecommendationApprovalProcessService, decision/lifecycle/sync services, AwardApprovalResolverService |
| Feedback | RecommendationFeedbackService, feedback context renderer/listener |
| Migration/reconciliation | RecommendationMigrationService and plugin commands |
| UI projection | RecommendationWorkflowUiService, RecommendationUiModeService, query/form services |
Mutation support traits contain shared mechanics, not controller entry points. State-changing code should call the owning concrete service.
Bestowal services
Bestowal services are separated by creation, form/query data, update, transition/handoff, cancellation, finalization, gathering/court-slot lookup, recommendation linking/synchronization, notification variables, field access, and link audit. AdHocBestowalService handles the corresponding ad-hoc path.
To-do services materialize/synchronize core ActionItems from templates, resolve assignees, and provide completion forms. Stable template item keys map to ActionItem source references so completed history survives definition changes. Bestowal locking serializes materialization, reconciliation, completion, cancellation, and finalization.
Court and integration services
CourtAgendaServiceowns court agenda/segment/item coordination.AwardsWorkflowProvider, actions, and conditions register workflow capabilities.AwardsNavigationProviderandAwardsViewCellProvidersupply UI integration.RecommendationApprovalContextRendererandRecommendationFeedbackContextRendererrender canonical approval context.BestowalTodoCompletionFormProviderintegrates with core ActionItem forms.
Service rules
- Enter the correct tenant before resolving any table or service dependency.
- Authorize in the controller/policy before calling a service.
- Keep related transitions and audit records in the service’s transaction/lock boundary.
- Return bounded domain failures; log unexpected details server-side.
- Dispatch workflow events only at the lifecycle point expected by the definition.
- Do not send raw ORM entities, secrets, or private recommendation text through queued payloads.
Verification
Use focused service tests for invariants and plugin/workflow tests for orchestration. For approval synchronization and bestowal to-do reconciliation, include retry/idempotency, lock contention, partial batch failure, preserved history, terminal-state rejection, and tenant isolation.