RecommendationApprovalWorkflowLifecycleService
in package
uses
LocatorAwareTrait
Owns workflow-backed lifecycle operations for recommendation approvals.
Table of Contents
Constants
- ACTIVE_STATUSES : array<int, string> = [\Awards\Model\Entity\RecommendationApprovalRun...
Properties
- $approvalRunsTable : Table
- $recommendationsTable : Table
- $workflowApprovalsTable : Table
- $workflowInstancesTable : Table
Methods
- __construct() : mixed
- approvalScopeRecommendationIds() : array<string|int, int>
- Return all recommendation IDs that share the same approval workflow scope.
- assertNoActiveRuns() : void
- cancelActiveRunsForAwardChange() : array<string|int, int>
- Cancel active approval workflows because the recommendation's award now uses another approval process.
- cancelActiveRunsForProcessRestart() : array<string|int, int>
- Cancel active approval workflows before restarting them from current configuration.
- cancelActiveRunsForRecommendationDeletion() : array<string|int, int>
- Mark active runs cancelled before deleting a recommendation.
- consumeLatestApprovedRunForBestowal() : int|null
- Record that an approved run was consumed by a created bestowal.
- findActiveRuns() : array<int, RecommendationApprovalRun>
- Return active approval runs for recommendations, normalized to approval scope.
- findLatestApprovedRunId() : int|null
- findLatestRun() : RecommendationApprovalRun|null
- Return the latest approval run in the recommendation's approval scope.
- hasActiveRun() : bool
- markRunsForBestowalCancellation() : array<string|int, int>
- Cancel consumed/superseded run projections tied to a cancelled bestowal.
- rehydrateUnlinkedRecommendations() : array<int, array<string, mixed>>
- Rehydrate approval workflows for recommendations whose prior approval was consumed or superseded.
- restartUnlinkedRecommendations() : array<int, array<string, mixed>>
- Start one clean approval cycle for each unlinked recommendation scope.
- supersedeActiveRunsForBestowalLink() : array<string|int, int>
- Cancel active approval workflows because their recommendation was linked to a bestowal.
- supersedeActiveRunsForGrouping() : array<string|int, int>
- Cancel active approval workflows that are superseded by grouping under another head.
- cancelWorkflowProjection() : void
- Keep workflow runtime rows terminal without depending on recommendation state.
- findLatestApprovedRun() : RecommendationApprovalRun|null
- findLatestRehydratableRun() : RecommendationApprovalRun|null
- markRunTerminal() : void
- resolveApprovalScopeRecommendationIds() : array<string|int, int>
Constants
ACTIVE_STATUSES
public
array<int, string>
ACTIVE_STATUSES
= [\Awards\Model\Entity\RecommendationApprovalRun::STATUS_IN_PROGRESS, \Awards\Model\Entity\RecommendationApprovalRun::STATUS_CHANGES_REQUESTED]
Properties
$approvalRunsTable
private
Table
$approvalRunsTable
$recommendationsTable
private
Table
$recommendationsTable
$workflowApprovalsTable
private
Table
$workflowApprovalsTable
$workflowInstancesTable
private
Table
$workflowInstancesTable
Methods
__construct()
public
__construct([Table|null $recommendationsTable = null ][, Table|null $approvalRunsTable = null ][, Table|null $workflowInstancesTable = null ][, Table|null $workflowApprovalsTable = null ]) : mixed
Parameters
- $recommendationsTable : Table|null = null
-
Optional recommendations table.
- $approvalRunsTable : Table|null = null
-
Optional recommendation approval runs table.
- $workflowInstancesTable : Table|null = null
-
Optional workflow instances table.
- $workflowApprovalsTable : Table|null = null
-
Optional workflow approvals table.
approvalScopeRecommendationIds()
Return all recommendation IDs that share the same approval workflow scope.
public
approvalScopeRecommendationIds(int $recommendationId[, bool $includeChildren = true ]) : array<string|int, int>
Parameters
- $recommendationId : int
-
Recommendation ID.
- $includeChildren : bool = true
-
Include grouped children when scoped to a group head.
Return values
array<string|int, int>assertNoActiveRuns()
public
assertNoActiveRuns(array<string|int, int> $recommendationIds, string $operation) : void
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $operation : string
-
Human-readable operation.
cancelActiveRunsForAwardChange()
Cancel active approval workflows because the recommendation's award now uses another approval process.
public
cancelActiveRunsForAwardChange(array<string|int, int> $recommendationIds, int|null $actorId) : array<string|int, int>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $actorId : int|null
-
Actor ID.
Return values
array<string|int, int> —Cancelled run IDs.
cancelActiveRunsForProcessRestart()
Cancel active approval workflows before restarting them from current configuration.
public
cancelActiveRunsForProcessRestart(array<string|int, int> $recommendationIds, int|null $actorId) : array<string|int, int>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $actorId : int|null
-
Actor ID.
Return values
array<string|int, int> —Cancelled run IDs.
cancelActiveRunsForRecommendationDeletion()
Mark active runs cancelled before deleting a recommendation.
public
cancelActiveRunsForRecommendationDeletion(array<string|int, int> $recommendationIds, int|null $actorId) : array<string|int, int>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $actorId : int|null
-
Actor ID.
Return values
array<string|int, int> —Cancelled run IDs.
consumeLatestApprovedRunForBestowal()
Record that an approved run was consumed by a created bestowal.
public
consumeLatestApprovedRunForBestowal(int $recommendationId, int $bestowalId, int $actorId) : int|null
Parameters
- $recommendationId : int
-
Recommendation ID.
- $bestowalId : int
-
Bestowal ID.
- $actorId : int
-
Actor ID.
Return values
int|null —Consumed run ID.
findActiveRuns()
Return active approval runs for recommendations, normalized to approval scope.
public
findActiveRuns(array<string|int, int> $recommendationIds[, bool $includeChildren = true ]) : array<int, RecommendationApprovalRun>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $includeChildren : bool = true
-
Include children for group heads.
Return values
array<int, RecommendationApprovalRun>findLatestApprovedRunId()
public
findLatestApprovedRunId(int $recommendationId) : int|null
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
int|nullfindLatestRun()
Return the latest approval run in the recommendation's approval scope.
public
findLatestRun(int $recommendationId) : RecommendationApprovalRun|null
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
RecommendationApprovalRun|nullhasActiveRun()
public
hasActiveRun(int $recommendationId) : bool
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
boolmarkRunsForBestowalCancellation()
Cancel consumed/superseded run projections tied to a cancelled bestowal.
public
markRunsForBestowalCancellation(int $bestowalId, int $actorId[, array<string|int, int> $recommendationIds = [] ]) : array<string|int, int>
Parameters
- $bestowalId : int
-
Bestowal ID.
- $actorId : int
-
Actor ID.
- $recommendationIds : array<string|int, int> = []
-
Recommendation scopes whose active runs must also be cancelled.
Return values
array<string|int, int> —Updated run IDs.
rehydrateUnlinkedRecommendations()
Rehydrate approval workflows for recommendations whose prior approval was consumed or superseded.
public
rehydrateUnlinkedRecommendations(array<string|int, int> $recommendationIds, int $actorId, string $reason) : array<int, array<string, mixed>>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $actorId : int
-
Actor ID.
- $reason : string
-
Rehydration reason.
Return values
array<int, array<string, mixed>> —Workflow dispatch results by recommendation ID.
restartUnlinkedRecommendations()
Start one clean approval cycle for each unlinked recommendation scope.
public
restartUnlinkedRecommendations(array<string|int, int> $recommendationIds, int $actorId, string $reason) : array<int, array<string, mixed>>
Unlike ordinary link removal, cancellation is a complete reconsideration: a fresh cycle is requested even when no rehydratable historical run exists.
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation or group-head IDs.
- $actorId : int
-
Actor ID.
- $reason : string
-
Restart reason.
Return values
array<int, array<string, mixed>> —Workflow dispatch requests by approval-scope ID.
supersedeActiveRunsForBestowalLink()
Cancel active approval workflows because their recommendation was linked to a bestowal.
public
supersedeActiveRunsForBestowalLink(array<string|int, int> $recommendationIds, int $bestowalId, int $actorId) : array<string|int, int>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs being linked.
- $bestowalId : int
-
Bestowal ID.
- $actorId : int
-
Actor performing the link.
Return values
array<string|int, int> —Superseded run IDs.
supersedeActiveRunsForGrouping()
Cancel active approval workflows that are superseded by grouping under another head.
public
supersedeActiveRunsForGrouping(array<string|int, int> $recommendationIds, int $headRecommendationId, int|null $actorId) : array<string|int, int>
This intentionally queries direct recommendation IDs instead of approval scope so the chosen head's workflow remains active while child workflows are cancelled.
Parameters
- $recommendationIds : array<string|int, int>
-
Child recommendation IDs being linked to a group head.
- $headRecommendationId : int
-
Group head recommendation ID.
- $actorId : int|null
-
Actor ID.
Return values
array<string|int, int> —Cancelled run IDs.
cancelWorkflowProjection()
Keep workflow runtime rows terminal without depending on recommendation state.
private
cancelWorkflowProjection(int $workflowInstanceId, string $reason) : void
Parameters
- $workflowInstanceId : int
-
Workflow instance ID.
- $reason : string
-
Cancellation reason.
findLatestApprovedRun()
private
findLatestApprovedRun(int $recommendationId) : RecommendationApprovalRun|null
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
RecommendationApprovalRun|nullfindLatestRehydratableRun()
private
findLatestRehydratableRun(int $recommendationId) : RecommendationApprovalRun|null
Parameters
- $recommendationId : int
-
Recommendation ID.
Return values
RecommendationApprovalRun|nullmarkRunTerminal()
private
markRunTerminal(RecommendationApprovalRun $run, string $status, string $reason, int|null $actorId[, int|null $consumedByBestowalId = null ][, int|null $supersededByBestowalId = null ]) : void
Parameters
- $run : RecommendationApprovalRun
-
Approval run.
- $status : string
-
Terminal status.
- $reason : string
-
Terminal reason.
- $actorId : int|null
-
Actor ID.
- $consumedByBestowalId : int|null = null
-
Consuming bestowal ID.
- $supersededByBestowalId : int|null = null
-
Superseding bestowal ID.
resolveApprovalScopeRecommendationIds()
private
resolveApprovalScopeRecommendationIds(array<string|int, int> $recommendationIds, bool $includeChildren) : array<string|int, int>
Parameters
- $recommendationIds : array<string|int, int>
-
Recommendation IDs.
- $includeChildren : bool
-
Include children for group heads.