KMP PHP API Reference

AwardsWorkflowActions
in package
uses LocatorAwareTrait, WorkflowContextAwareTrait

Workflow action implementations for award recommendation operations.

Provides workflow-backed award recommendation and bestowal operations.

Table of Contents

Properties

$Bestowals  : BestowalsTable
$Recommendations  : RecommendationsTable
$RecommendationsStatesLogs  : RecommendationsStatesLogsTable
$adHocBestowalService  : AdHocBestowalService
$approvalProcessService  : RecommendationApprovalProcessService
$bestowalCancellationService  : BestowalCancellationService
$bestowalCreationService  : BestowalCreationService
$bestowalHandoffService  : BestowalHandoffService
$bestowalRecommendationSyncService  : BestowalRecommendationSyncService
$bestowalsTable  : Table
$bestowalUpdateService  : BestowalUpdateService
$deletionService  : RecommendationDeletionService
$groupingService  : RecommendationGroupingService
$recommendationsTable  : Table
$stateLogService  : RecommendationStateLogService
$submissionService  : RecommendationSubmissionService
$transitionService  : RecommendationTransitionService
$updateService  : RecommendationUpdateService

Methods

__construct()  : mixed
advanceApprovalProcess()  : array<string, mixed>
Advance the recommendation approval process projection after an approval response.
assignGathering()  : array<string|int, mixed>
Assign a gathering to a recommendation.
cancelBestowal()  : array<string|int, mixed>
Cancel a bestowal and unwind linked recommendations.
createBestowal()  : array<string|int, mixed>
Create a bestowal from a single recommendation.
createBestowalsForRecommendations()  : array<string|int, mixed>
Create bestowals for each recommendation ID in the payload.
createFeedbackApproval()  : array<string|int, mixed>
Create a workflow approval for a recommendation feedback recipient and link it back to the recipient row so the recipient can respond from the approvals queue.
createRecommendation()  : array<string|int, mixed>
Create a new recommendation with initial status and state.
createStateLog()  : array<string|int, mixed>
Record a state transition in the audit log.
deleteRecommendation()  : array<string|int, mixed>
Delete a recommendation through the shared mutation service.
groupRecommendations()  : array<string|int, mixed>
Group recommendations under a shared head recommendation.
pullCourtPreferences()  : array<string|int, mixed>
Look up court availability preferences for the recommendation's member.
recordAdHocBestowal()  : array<string|int, mixed>
Record an ad-hoc bestowal without requiring linked recommendations.
removeRecommendationFromGroup()  : array<string|int, mixed>
Remove a single recommendation from its current group.
startApprovalProcess()  : array<string, mixed>
Start the configured recommendation approval process projection.
syncRecommendationsFromBestowal()  : array<string|int, mixed>
Sync linked recommendations from a bestowal's current state mapping.
transitionRecommendation()  : array<string|int, mixed>
Transition a recommendation through the shared state-machine service.
ungroupRecommendations()  : array<string|int, mixed>
Ungroup all children from a recommendation head.
updateBestowal()  : array<string|int, mixed>
Update a bestowal from edit form data including link changes.
updateRecommendation()  : array<string|int, mixed>
Update an existing recommendation through the shared mutation service.
resolveValue()  : mixed
Resolve a config value from context if it starts with '$.'.
currentApprovalStepContextUpdate()  : array<string, mixed>
Publish the active approval-step output at a stable workflow context path for reusable approval gates.
extractAdHocBestowalData()  : array<string, mixed>
Build ad-hoc bestowal input data from nested or flat workflow params.
extractNullableActorId()  : int|null
Resolve an actor ID when present.
extractRecommendationData()  : array<string, mixed>
Build mutation input data from either a nested data payload or flat config fields.
extractRecommendationIds()  : array<int, int>
Resolve recommendation IDs from workflow config.
extractRequesterContext()  : array{id: int, sca_name: string, email_address: string, phone_number: string|null}|null
Extract a normalized authenticated requester context.
formatMutationResult()  : array<string, mixed>
Convert a service mutation result to workflow-engine action output.
mapConfigFields()  : array<string, mixed>
Map flat action params to recommendation field names.
mapPayloadFields()  : array<string, mixed>
Map camelCase workflow payload keys to entity field names while preserving snake_case inputs.
parseAtomDeadline()  : DateTime|null
Parse an ATOM/ISO-8601 deadline string into a DateTime, tolerating empties and bad input.
resolveConfigArray()  : array<string, mixed>
Resolve a nested object/array config value.
syncConvertedRecommendationState()  : void
Advance converted recommendations onto the board after a workflow conversion.

Properties

Methods

__construct()

public __construct([RecommendationSubmissionService|null $submissionService = null ][, RecommendationUpdateService|null $updateService = null ][, RecommendationTransitionService|null $transitionService = null ][, RecommendationGroupingService|null $groupingService = null ][, RecommendationDeletionService|null $deletionService = null ][, RecommendationStateLogService|null $stateLogService = null ][, BestowalCreationService|null $bestowalCreationService = null ][, BestowalRecommendationSyncService|null $bestowalRecommendationSyncService = null ][, BestowalCancellationService|null $bestowalCancellationService = null ][, BestowalUpdateService|null $bestowalUpdateService = null ][, AdHocBestowalService|null $adHocBestowalService = null ][, RecommendationApprovalProcessService|null $approvalProcessService = null ][, BestowalHandoffService|null $bestowalHandoffService = null ]) : mixed
Parameters
$submissionService : RecommendationSubmissionService|null = null

Submission workflow service.

$updateService : RecommendationUpdateService|null = null

Update workflow service.

$transitionService : RecommendationTransitionService|null = null

Transition workflow service.

$groupingService : RecommendationGroupingService|null = null

Grouping workflow service.

$deletionService : RecommendationDeletionService|null = null

Deletion workflow service.

$stateLogService : RecommendationStateLogService|null = null

State-log workflow service.

$bestowalCreationService : BestowalCreationService|null = null

Bestowal creation service.

$bestowalRecommendationSyncService : BestowalRecommendationSyncService|null = null

Bestowal sync service.

$bestowalCancellationService : BestowalCancellationService|null = null

Bestowal cancellation service.

$bestowalUpdateService : BestowalUpdateService|null = null

Bestowal update service.

$adHocBestowalService : AdHocBestowalService|null = null

Ad-hoc bestowal service.

$approvalProcessService : RecommendationApprovalProcessService|null = null

Approval process service.

$bestowalHandoffService : BestowalHandoffService|null = null

Workflow-aware bestowal handoff service.

advanceApprovalProcess()

Advance the recommendation approval process projection after an approval response.

public advanceApprovalProcess(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context.

$config : array<string|int, mixed>

Node config.

Return values
array<string, mixed>

assignGathering()

Assign a gathering to a recommendation.

public assignGathering(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, gatheringId

Return values
array<string|int, mixed> —

Output with success

cancelBestowal()

Cancel a bestowal and unwind linked recommendations.

public cancelBestowal(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with bestowalId, closeReason, actorId

Return values
array<string|int, mixed> —

Workflow action result

createBestowal()

Create a bestowal from a single recommendation.

public createBestowal(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, actorId

Return values
array<string|int, mixed> —

Workflow action result

createBestowalsForRecommendations()

Create bestowals for each recommendation ID in the payload.

public createBestowalsForRecommendations(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationIds, actorId, optional gatheringId

Return values
array<string|int, mixed> —

Workflow action result

createFeedbackApproval()

Create a workflow approval for a recommendation feedback recipient and link it back to the recipient row so the recipient can respond from the approvals queue.

public createFeedbackApproval(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>

Invoked by the awards-recommendation-feedback-request workflow action node. Fires once per recipient (one workflow instance per RecommendationFeedbackRequested event). Idempotent at the recipient-row level: a replayed event returns the existing approval id instead of creating a duplicate. Throws on any invariant violation so the engine marks the action node failed rather than silently advancing to the end node.

Parameters
$context : array<string|int, mixed>

Workflow context (includes instanceId and the trigger payload).

$config : array<string|int, mixed>

Resolved node config: recipientId (member id), feedbackRequestRecipientId (recipient row id), deadline (ATOM string), nodeId (action node id), and optional decisionPromptLabel.

Tags
throws
RuntimeException

When required context is missing, the execution log or recipient row cannot be resolved, the recipient is not pending, or linking the approval fails.

Return values
array<string|int, mixed> —

Output with success and approvalId.

createRecommendation()

Create a new recommendation with initial status and state.

public createRecommendation(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with awardId, requesterScaName, memberScaName, contactEmail, reason, and optional fields

Return values
array<string|int, mixed> —

Output with success, recommendationId

createStateLog()

Record a state transition in the audit log.

public createStateLog(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, fromState, toState, fromStatus, toStatus, actorId

Return values
array<string|int, mixed> —

Output with success, logId

deleteRecommendation()

Delete a recommendation through the shared mutation service.

public deleteRecommendation(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, actorId, optional gatheringId

Return values
array<string|int, mixed> —

Workflow action result

groupRecommendations()

Group recommendations under a shared head recommendation.

public groupRecommendations(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationIds, actorId

Return values
array<string|int, mixed> —

Workflow action result

pullCourtPreferences()

Look up court availability preferences for the recommendation's member.

public pullCourtPreferences(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId

Return values
array<string|int, mixed> —

Output with success, courtAvailability

recordAdHocBestowal()

Record an ad-hoc bestowal without requiring linked recommendations.

public recordAdHocBestowal(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with data payload and actorId

Return values
array<string|int, mixed> —

Workflow action result

removeRecommendationFromGroup()

Remove a single recommendation from its current group.

public removeRecommendationFromGroup(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId/childId, actorId

Return values
array<string|int, mixed> —

Workflow action result

startApprovalProcess()

Start the configured recommendation approval process projection.

public startApprovalProcess(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context.

$config : array<string|int, mixed>

Node config with recommendationId and optional actorId.

Return values
array<string, mixed>

syncRecommendationsFromBestowal()

Sync linked recommendations from a bestowal's current state mapping.

public syncRecommendationsFromBestowal(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with bestowalId, actorId

Return values
array<string|int, mixed> —

Workflow action result

transitionRecommendation()

Transition a recommendation through the shared state-machine service.

public transitionRecommendation(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, targetState, actorId, and optional transition data

Return values
array<string|int, mixed> —

Workflow action result

ungroupRecommendations()

Ungroup all children from a recommendation head.

public ungroupRecommendations(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId/headId, actorId

Return values
array<string|int, mixed> —

Workflow action result

updateBestowal()

Update a bestowal from edit form data including link changes.

public updateBestowal(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with bestowalId, data, actorId

Return values
array<string|int, mixed> —

Workflow action result

updateRecommendation()

Update an existing recommendation through the shared mutation service.

public updateRecommendation(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string|int, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Config with recommendationId, data, actorId

Return values
array<string|int, mixed> —

Workflow action result

resolveValue()

Resolve a config value from context if it starts with '$.'.

protected resolveValue(mixed $value, array<string|int, mixed> $context) : mixed
Parameters
$value : mixed

Raw value or context path (e.g. '$.trigger.memberId')

$context : array<string|int, mixed>

Current workflow context

Return values
mixed —

Resolved value

currentApprovalStepContextUpdate()

Publish the active approval-step output at a stable workflow context path for reusable approval gates.

private currentApprovalStepContextUpdate(bool $success, array<string, mixed> $data) : array<string, mixed>
Parameters
$success : bool

Whether the workflow action succeeded.

$data : array<string, mixed>

Action data payload.

Return values
array<string, mixed>

extractAdHocBestowalData()

Build ad-hoc bestowal input data from nested or flat workflow params.

private extractAdHocBestowalData(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

Return values
array<string, mixed>

extractNullableActorId()

Resolve an actor ID when present.

private extractNullableActorId(array<string|int, mixed> $context, array<string|int, mixed> $config) : int|null
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

Return values
int|null

extractRecommendationData()

Build mutation input data from either a nested data payload or flat config fields.

private extractRecommendationData(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<string, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

Return values
array<string, mixed>

extractRecommendationIds()

Resolve recommendation IDs from workflow config.

private extractRecommendationIds(array<string|int, mixed> $context, array<string|int, mixed> $config) : array<int, int>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

Return values
array<int, int>

extractRequesterContext()

Extract a normalized authenticated requester context.

private extractRequesterContext(array<string|int, mixed> $context, array<string|int, mixed> $config) : array{id: int, sca_name: string, email_address: string, phone_number: string|null}|null
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

Return values
array{id: int, sca_name: string, email_address: string, phone_number: string|null}|null

formatMutationResult()

Convert a service mutation result to workflow-engine action output.

private formatMutationResult(array<string, mixed> $result) : array<string, mixed>
Parameters
$result : array<string, mixed>

Shared mutation service result

Return values
array<string, mixed>

mapConfigFields()

Map flat action params to recommendation field names.

private mapConfigFields(array<string|int, mixed> $context, array<string|int, mixed> $config, array<string, string> $fieldMap) : array<string, mixed>
Parameters
$context : array<string|int, mixed>

Current workflow context

$config : array<string|int, mixed>

Workflow node/action config

$fieldMap : array<string, string>

Config key => entity field

Return values
array<string, mixed>

mapPayloadFields()

Map camelCase workflow payload keys to entity field names while preserving snake_case inputs.

private mapPayloadFields(array<string, mixed> $payload, array<string, string> $fieldMap) : array<string, mixed>
Parameters
$payload : array<string, mixed>

Workflow payload data.

$fieldMap : array<string, string>

Payload key => entity field.

Return values
array<string, mixed>

parseAtomDeadline()

Parse an ATOM/ISO-8601 deadline string into a DateTime, tolerating empties and bad input.

private parseAtomDeadline(mixed $value) : DateTime|null
Parameters
$value : mixed

Raw deadline value from the trigger payload.

Return values
DateTime|null —

Parsed deadline, or null when absent/unparseable.

resolveConfigArray()

Resolve a nested object/array config value.

private resolveConfigArray(mixed $value, array<string|int, mixed> $context) : array<string, mixed>
Parameters
$value : mixed

Config value or context path

$context : array<string|int, mixed>

Current workflow context

Return values
array<string, mixed>

syncConvertedRecommendationState()

Advance converted recommendations onto the board after a workflow conversion.

private syncConvertedRecommendationState(array<string, mixed> $result, int $actorId) : void

Manual board transitions manage recommendation states explicitly; the workflow conversion path has no such step, so without this sync the recommendation stays in "Submitted" forever.

Parameters
$result : array<string, mixed>

Handoff result payload.

$actorId : int

Acting member ID.

On this page

Search results