RecognitionManager

Need help? Ask Kademi

Owns the recognition domain: topics, levels, badges, periods, awards, points allocations and nominations that make up Kademi's gamification and leaderboard features. Registered as the "recognitionManager" service, so its exported methods are reachable from server-side JS as recognitionManager.methodName(...). As a StartableService it also wires up the event listeners that trigger an automatic recognition scan: profile subscription changes, module progress, sales data records and reward grant or debit events all funnel through to rescan the affected topics' levels, and a scheduled job periodically fires or cancels due level notifications.

Group: Managers

Implements: StartableService

Properties

Property	Returns	Description
allRecognitionPointsRuleTypes	`List<RecognitionPointsRuleType>`	The recognition points rule types registered in the account, used to calculate points for a level or badge from a formula rather than a fixed amount.
appIndexers	`List<AppIndexer>`	The search indexers this manager contributes to the account's search index - currently just the indexer for recognition period results, so leaderboard results can be found through search.
periodicTopics	`List<RecognitionTopic>`	Every periodic recognition topic configured for the current tenant organisation.
recognitionService	RecognitionService	The underlying recognition service that this manager delegates most of its calculations and persistence to.
topics	`List<RecognitionTopic>`	Every recognition topic configured for the current tenant organisation.

Methods

`getAppIndexers()`

Returns: List<AppIndexer>

The search indexers this manager contributes to the account's search index - currently just the indexer for recognition period results, so leaderboard results can be found through search.

`parsePointsRuleConfig(BaseRecognition recognition)`

Returns: Map<String,String>

Parses a recognition's stored points rule configuration string into a map of parameter name to value, for the recognition's configured points rule type to use when calculating points.

Parameter	Description
`recognition`	the recognition whose points rule configuration should be parsed

`buildRecognitionPointsDescription(BaseRecognition recognition)`

Returns: String

Builds a human-readable description of a recognition's configured points rule, by parsing its stored configuration and asking the matching points rule type to describe it. Returns null if the recognition has no points rule type configured, or a warning string if the configured rule type id is not registered.

Parameter	Description
`recognition`	the recognition to describe the points rule for

`duplicatePeriod(RecognitionPeriod sourcePeriod, Organisation parentOrg, Date start, Date end)`

Returns: RecognitionPeriod

Duplicates a recognition period for a different organisation: clones the source period's promotion, scopes the new promotion's participant selector to the given organisation, and creates a new period linking to it under the source period's topic. Used to roll a periodic topic's promotion out to a new organisation without recreating its configuration by hand. Requires a logged in user, and the source period must not already be deleted.

Parameter	Description
`sourcePeriod`	the period whose promotion configuration should be duplicated
`parentOrg`	the organisation the new period's promotion is scoped to
`start`	the start date of the new period's promotion
`end`	the end date of the new period's promotion

`deletePeriodResults(RecognitionPeriod period)`

Returns: void

Deletes every recorded result (ranking row) for a recognition period, without affecting the period itself, its awards, or its points allocations. Used before rescanning a period so stale rankings do not linger alongside freshly calculated ones.

Parameter	Description
`period`	the period whose results should be deleted

`closePeriod(RecognitionPeriod period)`

Returns: void

Finalises a recognition period: awards each participant's final points for the period (topping up a continuous-mode topic's already-reconciled points, or awarding the outstanding lump sum for an award-on-level-reached topic) and marks the period as processed. This is one-way - a dry-run topic has nothing real to close, and closing again, or before results have been calculated, is rejected.

Parameter	Description
`period`	the period to close

`getAllRecognitionPointsRuleTypes()`

Returns: List<RecognitionPointsRuleType>

The recognition points rule types registered in the account, used to calculate points for a level or badge from a formula rather than a fixed amount.

`findRecognitionPointsRuleType(String id)`

Returns: RecognitionPointsRuleType

Finds a registered recognition points rule type by its id.

Parameter	Description
`id`	the rule type's id

`newCalcContext()`

Returns: CalcContext

Creates a fresh, empty calculation context for tracking cache state and call depth across a single recognition value calculation. Callers that want several calculations to share cached lookups should create one explicitly and pass it through, rather than relying on the overloads that create a new one per call.

`calcCurrentValue(RecognitionTopic topic, BaseEntity participant)`

Returns: BigDecimal

Calculates a participant's current value for a topic (for example, total sales or total points, depending on the topic's data source), using a fresh calculation context. This is potentially expensive - prefer the overload that accepts a CalcContext when making several calculations together, so cached lookups can be reused.

Parameter	Description
`topic`	the topic to calculate the current value for
`participant`	the participant to calculate the current value for

`calcCurrentValue(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)`

Returns: BigDecimal

Calculates a participant's current value for a topic (for example, total sales or total points, depending on the topic's data source), for a non-periodic topic. Potentially expensive - may query source records or run a metric calculation depending on the topic's configuration.

Parameter	Description
`topic`	the topic to calculate the current value for
`participant`	the participant to calculate the current value for
`calcContext`	the calculation context to use, allowing cached lookups to be reused across several calculations

`calcCurrentValueForPeriod(RecognitionPeriod period, BaseEntity participant)`

Returns: BigDecimal

Calculates a participant's current value for a single period of a periodic topic, using a fresh calculation context.

Parameter	Description
`period`	the period to calculate the current value for
`participant`	the participant to calculate the current value for

`calcCurrentValueForPeriod(RecognitionPeriod period, BaseEntity participant, CalcContext calcContext)`

Returns: BigDecimal

Calculates a participant's current value for a single period of a periodic topic, scoped to the period's start and end dates.

Parameter	Description
`period`	the period to calculate the current value for
`participant`	the participant to calculate the current value for
`calcContext`	the calculation context to use, allowing cached lookups to be reused across several calculations

`findPeriodForDate(RecognitionTopic topic, Date now, BaseEntity participant)`

Returns: RecognitionPeriod

Finds the recognition period for which the given participant is eligible and which covers the given date. Returns null if no suitable period can be found, or if the topic is not configured for periodicity.

Parameter	Description
`topic`	the topic to find a period within
`now`	the date the period must cover
`participant`	the participant who must be eligible for the period

`findAllPeriodsForDate(RecognitionTopic topic, Date now)`

Returns: List<RecognitionPeriod>

Finds every period in a topic that covers the given date. For most topics this returns at most one period, but overlapping periods are technically possible, so this returns all of them rather than assuming uniqueness.

Parameter	Description
`topic`	the topic to find periods within
`now`	the date the periods must cover

`periodLeaderboard(RecognitionPeriod period)`

Returns: RecognitionPeriodLeaderboard

Builds a leaderboard helper for a recognition period, used to page through ranked results and look up the current user's own ranking without repeating the underlying query each time.

Parameter	Description
`period`	the period to build a leaderboard for

`findParticipants(RecognitionTopic topic)`

Returns: Collection<? extends BaseEntity>

Finds every entity currently eligible to participate in a topic - a profile or organisation, depending on whether the topic is configured for organisation-level awards.

Parameter	Description
`topic`	the topic to find participants for

`findParticipantsForPeriod(RecognitionPeriod period)`

Returns: Collection<? extends BaseEntity>

Finds every entity currently eligible to participate in a recognition period.

Parameter	Description
`period`	the period to find participants for

`isElligibleForTopicLevels(RecognitionTopic topic, BaseEntity participant)`

Returns: boolean

Whether the given participant is eligible to participate in level awards for a non-periodic topic.

Parameter	Description
`topic`	the topic to check eligibility for
`participant`	the participant to check eligibility for

`scanPeriod(RecognitionPeriod period)`

Returns: void

Scans every eligible participant of a recognition period, recalculating and recording each one's level and points, then updates the period's rankings. This is the main entry point for recalculating a whole period's results, for example after configuration changes or as part of a scheduled or manually triggered scan.

Parameter	Description
`period`	the period to scan

`scanLevels(RecognitionTopic topic, BaseEntity participant)`

Returns: void

Recalculates and records the given participant's level and points for a non-periodic topic.

Parameter	Description
`topic`	the topic to scan levels for, ignored (no-op) if null
`participant`	the participant to scan, ignored (no-op) if null

`scanLevels(RecognitionPeriod period, BaseEntity participant)`

Returns: void

Recalculates and records the given participant's level and points for a single period of a periodic topic.

Parameter	Description
`period`	the period to scan levels for
`participant`	the participant to scan

`getLevelStatus(RecognitionTopic topic, BaseEntity participant)`

Returns: LevelStatus

The given participant's current level status for a non-periodic topic - their current level, the next level up, and their progress towards it - calculated with a fresh calculation context.

Parameter	Description
`topic`	the topic to get the level status for
`participant`	the participant to get the level status for

`getLevelStatus(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)`

Returns: LevelStatus

The given participant's current level status for a non-periodic topic - their current level, the next level up, and their progress towards it.

Parameter	Description
`topic`	the topic to get the level status for
`participant`	the participant to get the level status for
`calcContext`	the calculation context to use, allowing cached lookups to be reused across several calculations

`buildLevelSummary(RecognitionTopic topic, BaseEntity participant)`

Returns: LevelSummary

Builds the full level ladder for a participant in a non-periodic topic, or where no period is in scope.

Parameter	Description
`topic`	the topic whose levels should be summarised
`participant`	the participant to resolve participant-specific level amounts for

`buildLevelSummary(RecognitionTopic topic, BaseEntity participant, RecognitionPeriod period)`

Returns: LevelSummary

Builds the full level ladder for a participant: one level summary item per level in the topic, ordered by the participant-specific level amount (which resolves data-series and lookup-table overrides rather than just the level's default amount), each paired with the next level up so a UI can render the range a participant must cross to advance. The final (highest) level has a null next level and next level amount, since there is nothing further to advance to.

Parameter	Description
`topic`	the topic whose levels should be summarised
`participant`	the participant to resolve participant-specific level amounts for
`period`	the currently relevant period, or null for a non-periodic topic

`nextLevel(RecognitionTopic topic, BigDecimal thisLevel, BaseEntity participant)`

Returns: Pair<RecognitionLevel,BigDecimal>

Finds the level whose participant-specific amount is the smallest amount still greater than the given level amount, ie the next level up from that amount.

Parameter	Description
`topic`	the topic to search levels within
`thisLevel`	the level amount to find the next level above
`participant`	the participant to resolve participant-specific level amounts for

`calcActualPointsAwarded(RecognitionTopic topic, BaseEntity participant)`

Returns: BigDecimal

Sums the points actually awarded to a participant for a topic, across all time rather than scoped to any single period, so an admin can compare it against the calculated points preview to see whether the participant has been paid what they are currently entitled to. For a continuous-mode topic this is the net of credits minus debits already reconciled via points allocations. For an award-once topic it is the sum of each non-deleted level award's own points credit - a regression debit under an award-once topic is never linked back to the topic in the data model, so is not reflected here; this matches the existing "total points" figure already shown for a topic's whole awards table.

Parameter	Description
`topic`	the topic to sum awarded points for
`participant`	the participant to sum awarded points for

`calcActualPointsAwarded(RecognitionPeriod period, BaseEntity participant)`

Returns: BigDecimal

Sums the points actually awarded to a participant for a period's topic. For a continuous-mode topic this is scoped to the given period (net of credits minus debits reconciled via points allocations); for an award-once topic it sums every level award's points credit for the topic across all periods, the same as the topic-only overload, since award-once points are not tracked per period.

Parameter	Description
`period`	the period whose topic to sum awarded points for
`participant`	the participant to sum awarded points for

`findPointsAllocations(RecognitionTopic topic, BaseEntity participant)`

Returns: List<PointsAllocation>

As the period-scoped overload, for a non-periodic topic or where no period is in scope. Velocity resolves overloads by the declared argument types, so a template holding a possibly-unset period reference must branch to this overload rather than passing the period reference through - passing an unset (or wrongly-typed) reference straight into the period-scoped overload fails to resolve at all.

Parameter	Description
`topic`	the topic to find allocations for
`participant`	the participant the allocation's credit or debit was issued to

`findPointsAllocations(RecognitionTopic topic, BaseEntity participant, RecognitionPeriod period)`

Returns: List<PointsAllocation>

Finds the points allocation records linked to any level under the given topic where the credit or debit was issued to the given participant, optionally scoped to a single period so a UI can show only the allocations relevant to that period. When scoped to a period, this also includes level-only allocations which have no period link at all - unlike the stricter continuous-points reconciliation lookup, this method is for display purposes, where a level-only allocation is still relevant to the participant and topic and should not be hidden just because it isn't tied to this particular period.

Parameter	Description
`topic`	the topic to find allocations for
`participant`	the participant the allocation's credit or debit was issued to
`period`	the period to scope allocations to, or null to return allocations across all periods (and non-periodic topics)

`findSourceRecords(RecognitionTopic topic, BaseEntity participant)`

Returns: List<?>

As the period-scoped overload, for a non-periodic topic or covering the topic's whole date range.

Parameter	Description
`topic`	the topic to find source records for
`participant`	the participant to find source records for

`findSourceRecords(RecognitionTopic topic, BaseEntity participant, RecognitionPeriod period)`

Returns: List<?>

Finds the underlying source records which feed into a topic's current value calculation for a participant. Only data-series and points-bucket topics are supported, since those are the only two types with a natural list of individual source records to show; elearning and metric topics return an empty list. At most MAX_SOURCE_RECORDS records are returned - there is no pagination, this is just a cap to avoid ever loading an unbounded result set.

Parameter	Description
`topic`	the topic to find source records for
`participant`	the participant to find source records for
`period`	the period to scope records to, for a periodic topic - pass null for a non-periodic topic

`achievementsSummary(BaseEntity participant)`

Returns: AchievementsSummary

Builds the achievements summary for a participant across every recognition topic in the account.

Parameter	Description
`participant`	the participant to summarise achievements for

`scanLevels(RecognitionTopic topic)`

Returns: void

Scans the current user for a non-periodic topic, recalculating and recording their level and points.

Parameter	Description
`topic`	the topic to scan levels for

`processDueLevelNotificationsForCurrentOrg()`

Returns: int

Fires (or cancels) every due level notification of every type, belonging to the current tenant organisation only. For manual invocation from the topic admin page, so an admin does not have to wait for the next scheduled run, and other accounts' notifications are left untouched.

`processDueLevelNotificationsForProfile(BaseEntity participant)`

Returns: int

As the current-org overload, but restricted to due notifications for a single participant. For manually testing the feature against one profile without firing every other due notification in the account.

Parameter	Description
`participant`	the profile (or org) to process due level notifications for

`processDueCloseToLevelNotificationsForCurrentOrg()`

Returns: int

As the current-org overload, but restricted to close-to-level notifications.

`processDueCloseToLevelNotificationsForProfile(BaseEntity participant)`

Returns: int

As the per-profile overload, but restricted to close-to-level notifications.

Parameter	Description
`participant`	the profile (or org) to process due close-to-level notifications for

`createAward(BaseRecognition recog, BaseEntity participant, Date awardedDate)`

Returns: RecognitionAward

Creates (or updates) a recognition award for a participant. If the participant already has an award for this recognition, its awarded date is updated instead of creating a duplicate.

Parameter	Description
`recog`	the recognition (level or badge) to award
`participant`	the participant to award it to
`awardedDate`	the date the award was earned

`findLevel(RecognitionTopic topic, BigDecimal value)`

Returns: RecognitionLevel

Finds the highest level in a topic whose default level amount the given value meets or exceeds. Uses each level's default amount for comparison, not any participant-specific override.

Parameter	Description
`topic`	the topic to search levels within, or null to get no match
`value`	the value to find the matching level for

`findLevelAmountForParticipant(RecognitionLevel level, BaseEntity participant)`

Returns: BigDecimal

The participant-specific amount at which the given level is reached, resolving any data-series or lookup-table override configured on the level rather than just its default amount.

Parameter	Description
`level`	the level to find the participant-specific amount for
`participant`	the participant to resolve the amount for

`findLevelAmountForParticipant(RecognitionPeriod period, RecognitionLevel level, BaseEntity participant)`

Returns: BigDecimal

As the period-less overload, but resolves the level amount within the context of a specific period, for a level whose data-series or lookup-table override is period-scoped.

Parameter	Description
`period`	the period to resolve the level amount within
`level`	the level to find the participant-specific amount for
`participant`	the participant to resolve the amount for

`findLevelAmount(RecognitionAward award)`

Returns: BigDecimal

The participant-specific amount at which the level of the given award was reached, resolved within the award's period if it has one.

Parameter	Description
`award`	the level award to find the level amount for

`hasLevel(RecognitionTopic topic, BigDecimal value)`

Returns: boolean

Whether the given value meets or exceeds any level's default amount in the topic.

Parameter	Description
`topic`	the topic to check
`value`	the value to check

`findPendingNominations()`

Returns: List<RecognitionNomination>

Every recognition nomination pending review for the current tenant organisation.

`findBadgesForNomination(Profile nominator, RecognitionTopic topic)`

Returns: List<RecognitionBadge>

Finds every badge in a topic that the given profile is allowed to nominate someone for, based on each badge's configured nominator selector. A badge with no nominator selector configured is excluded, since it has no restriction to check against.

Parameter	Description
`nominator`	the profile who would be making the nomination
`topic`	the topic to find nominatable badges within

`awardBadge(RecognitionBadge badge, BaseEntity awardToEntity)`

Returns: RecognitionAward

Awards a badge to an entity, unless they already have it - in which case this is a no-op that returns null rather than creating a duplicate award.

Parameter	Description
`badge`	the badge to award
`awardToEntity`	the entity to award the badge to

`awardBadge(RecognitionBadge badge, BaseEntity awardToEntity, Date awardDate)`

Returns: RecognitionAward

As the two-argument overload, but with an explicit awarded date rather than the current date.

Parameter	Description
`badge`	the badge to award
`awardToEntity`	the entity to award the badge to
`awardDate`	the date the badge was earned

`removeAwardBadge(RecognitionBadge badge, BaseEntity awardToEntity)`

Returns: void

Removes a participant's award of a badge, if they have one. Logs a warning and does nothing if they do not currently have the badge.

Parameter	Description
`badge`	the badge to remove
`awardToEntity`	the entity to remove the badge from

`getBadge(long id)`

Returns: RecognitionBadge

Finds a recognition badge by id, scoped to the current tenant organisation.

Parameter	Description
`id`	the badge's id

`findPeriod(long id)`

Returns: RecognitionPeriod

Finds a recognition period by id, scoped to the current tenant organisation.

Parameter	Description
`id`	the period's id

`findAward(long id)`

Returns: RecognitionAward

Finds a recognition award by id, scoped to the current tenant organisation.

Parameter	Description
`id`	the award's id

`deleteAward(RecognitionAward award)`

Returns: void

Deletes a recognition award, firing a recognition-lost event first so listeners can react (for example, a funnel automation) before the award record is removed.

Parameter	Description
`award`	the award to delete, ignored (no-op) if null

`deleteRecognition(BaseRecognition recog)`

Returns: void

Physically deletes a recognition (level or badge) and every award linked to it.

Parameter	Description
`recog`	the recognition to delete

`isRelatedToPeriodResult(BaseRecognition recog)`

Returns: boolean

Whether a recognition (level or badge) is linked to any period result, either directly or through one of its awards. Used to warn before a destructive change that would affect period results already calculated for it.

Parameter	Description
`recog`	the recognition to check

`getNomination(long id)`

Returns: RecognitionNomination

Finds a recognition nomination by id, scoped to the current tenant organisation.

Parameter	Description
`id`	the nomination's id

`createNomination(RecognitionBadge badge, Profile nominee, Profile nominator, String reason)`

Returns: RecognitionNomination

Creates a nomination of a profile for a badge by another profile, first validating both against the badge's configured nominee and nominator selectors and rejecting the nomination if either is not eligible.

Parameter	Description
`badge`	the badge being nominated for
`nominee`	the profile being nominated
`nominator`	the profile making the nomination
`reason`	the reason given for the nomination

`createTopic(String topicName, String topicTitle)`

Returns: RecognitionTopic

Creates a new recognition topic and reports its creation to account telemetry.

Parameter	Description
`topicName`	the unique, path-safe name for the topic
`topicTitle`	the display title for the topic

`createAssetForRecognition(BaseRecognition r, ContentType type)`

Returns: Asset

Creates a content asset for a recognition (level or badge) and links it to the recognition's asset id.

Parameter	Description
`r`	the recognition to create an asset for
`type`	the type of content asset to create

`processNomination(RecognitionNomination nomination, Profile currentUser, boolean accept)`

Returns: void

Accepts or rejects a recognition nomination. Accepting also creates the award for the nominated badge; rejecting just records the rejection.

Parameter	Description
`nomination`	the nomination to process
`currentUser`	the profile processing the nomination
`accept`	true to accept the nomination, false to reject it

`findBaseRecognitionAssetTypes()`

Returns: Set<ContentType>

The content types applicable for a recognition's image asset.

`findTopic(String topicName)`

Returns: RecognitionTopic

Finds a recognition topic by name, scoped to the current tenant organisation.

Parameter	Description
`topicName`	the topic's unique name

`findTopicById(long id)`

Returns: RecognitionTopic

Finds a recognition topic by id.

Parameter	Description
`id`	the topic's id

`getCurrentLevelAward(RecognitionTopic topic, BaseEntity participant)`

Returns: RecognitionAward

The highest level award the given participant currently holds in a topic - their current level.

Parameter	Description
`topic`	the topic to find the current level award for
`participant`	the participant to find the current level award for

`findStagingLinks(RecognitionTopic topic)`

Returns: List<StagingLink>

A single-item list linking to a topic's dry-run preview spreadsheet, if it has already been created.

Parameter	Description
`topic`	the topic to find a dry-run staging link for

`findStagingLinks(RecognitionPeriod period)`

Returns: List<StagingLink>

A single-item list linking to a recognition period's own dry-run preview spreadsheet, if it has already been created.

Parameter	Description
`period`	the period to find a dry-run staging link for

`deleteStagedPoints(RecognitionTopic topic)`

Returns: void

Permanently discards every row recorded for a recognition topic's dry-run preview, without awarding anything - dry-run never creates any real records to award in the first place, so to get real points, temporarily switch the topic off dry-run and run it for real instead.

Parameter	Description
`topic`	the recognition topic to clear the dry-run preview for

`deleteStagedPoints(RecognitionPeriod period)`

Returns: void

Permanently discards every row recorded for a recognition period's own dry-run preview, without awarding anything.

Parameter	Description
`period`	the period to clear the dry-run preview for

`getTopics()`

Returns: List<RecognitionTopic>

Every recognition topic configured for the current tenant organisation.

`getPeriodicTopics()`

Returns: List<RecognitionTopic>

Every periodic recognition topic configured for the current tenant organisation.

`forceCurrentLevel(BaseEntity participant, RecognitionLevel newLevel, Date awardedDate)`

Returns: RecognitionAward

Forces a participant directly to a given level for a non-periodic topic, overriding whatever their calculated level would be. Requires a logged in user.

Parameter	Description
`participant`	the participant to force the level for
`newLevel`	the level to force the participant to
`awardedDate`	the date to record the award as earned, or null to use the current date

`forceCurrentLevel(BaseEntity participant, RecognitionLevel newLevel, Date awardedDate, RecognitionPeriod period)`

Returns: RecognitionAward

As the three-argument overload, but scoped to a single period of a periodic topic.

Parameter	Description
`participant`	the participant to force the level for
`newLevel`	the level to force the participant to
`awardedDate`	the date to record the award as earned, or null to use the current date
`period`	the period to force the level within

`getRecognitionService()`

Returns: RecognitionService

The underlying recognition service that this manager delegates most of its calculations and persistence to.

`findAwardsForEntity(BaseEntity baseEntity)`

Returns: List<RecognitionAward>

Every recognition award ever made to the given entity, across every topic.

Parameter	Description
`baseEntity`	the entity to find awards for

`findLevelAwards(BaseEntity participant, RecognitionTopic topic)`

Returns: List<RecognitionAward>

Every level award (excluding badge awards) made to a participant within a topic.

Parameter	Description
`participant`	the participant to find level awards for
`topic`	the topic to find level awards within

`findLevelAwardsForPeriod(BaseEntity participant, RecognitionPeriod period)`

Returns: List<RecognitionAward>

Every level award made to a participant within a single period of a topic.

Parameter	Description
`participant`	the participant to find level awards for
`period`	the period to find level awards within

`findBadgeAwards(BaseEntity participant, RecognitionTopic topic)`

Returns: List<RecognitionAward>

Every badge award (excluding level awards) made to a participant within a topic.

Parameter	Description
`participant`	the participant to find badge awards for
`topic`	the topic to find badge awards within

`findParticipants(BaseEntity entity, RecognitionTopic t)`

Returns: List<? extends BaseEntity>

Finds every participant for a topic that is related to the given entity - not just the entity itself, but every entity related to it that is eligible to participate.

Parameter	Description
`entity`	the entity to find related participants for
`t`	the topic to find participants within

`findParticipantsForPeriod(BaseEntity entity, RecognitionPeriod period)`

Returns: List<? extends BaseEntity>

For the given entity (typically the current user), finds the participants relevant to a recognition period. If the entity is a profile and the period's promotion is profile-based, the entity itself is returned; if the promotion is organisation-based, this returns the organisations the entity has access to which are eligible for the promotion.

Parameter	Description
`entity`	the entity to find participants for
`period`	the period to find participants within

`startTopicScan(RecognitionTopic topic)`

Returns: AsyncJob

Starts an asynchronous full scan of a non-periodic topic, recalculating levels for every participant. Not valid for a periodic topic, which must be scanned one period at a time instead.

Parameter	Description
`topic`	the topic to scan

`startTopicScan(RecognitionTopic topic, boolean revertToDryRunAfterComplete)`

Returns: AsyncJob

Starts an asynchronous full scan of a non-periodic topic, recalculating levels for every participant. Not valid for a periodic topic, which must be scanned one period at a time instead.

Parameter	Description
`topic`	the topic to scan
`revertToDryRunAfterComplete`	when true, the topic's calc mode is switched back to dry-run once the scan finishes, regardless of what calc mode was in effect while it ran. Used to allow a single real-points scan on a dry-run topic without leaving it permanently out of dry-run mode.

`startTopicScan(RecognitionPeriod period)`

Returns: AsyncJob

Starts an asynchronous scan of a single period, recalculating levels for every participant in that period.

Parameter	Description
`period`	the period to scan

`startTopicScan(RecognitionPeriod period, boolean revertToDryRunAfterComplete)`

Returns: AsyncJob

Starts an asynchronous scan of a single period, recalculating levels for every participant in that period. Not valid for a period that has already been closed.

Parameter	Description
`period`	the period to scan
`revertToDryRunAfterComplete`	when true, the period's topic is switched back to dry-run once the scan finishes, regardless of what calc mode was in effect while it ran. Used to allow a single real-points scan (publish or re-publish results) on a dry-run periodic topic without leaving it permanently out of dry-run mode.

`createLevel(RecognitionTopic topic, String levelName, String levelTitle, Object levelAmount)`

Returns: RecognitionLevel

Creates a level in a topic with a fixed threshold amount.

Parameter	Description
`topic`	the topic to create the level in
`levelName`	the unique, path-safe name for the level
`levelTitle`	the display title for the level
`levelAmount`	the threshold amount at which the level is reached, coerced to a number

`newLevelBuilder(RecognitionTopic topic, String levelName)`

Returns: RecognitionLevelBuilder

Creates a new level builder for configuring and creating a level in a topic.

Parameter	Description
`topic`	the topic to create the level in
`levelName`	the unique, path-safe name for the level

`createRecognitionPeriod(RecognitionTopic topic, Reward promotion)`

Returns: RecognitionPeriod

Creates a new period for a periodic topic, linked to the given promotion.

Parameter	Description
`topic`	the topic to create the period in
`promotion`	the promotion (reward) the period is linked to

`findPeriodResults(RecognitionPeriod period, int startPos, int pageSize)`

Returns: List<RecognitionPeriodResult>

A page of ranked results for a recognition period, for showing a leaderboard.

Parameter	Description
`period`	the period to find results for
`startPos`	the zero-based index of the first result to return
`pageSize`	the maximum number of results to return

`countPeriodResults(RecognitionPeriod period)`

Returns: long

The total number of results recorded for a recognition period.

Parameter	Description
`period`	the period to count results for

`findPeriodResults(RecognitionPeriod period, int max)`

Returns: List<RecognitionPeriodResult>

The highest-ranked results for a recognition period, up to a maximum count. Can be used to show leaderboards.

Parameter	Description
`period`	the period to find results for
`max`	the maximum number of results to return

`findPeriodResultForParticipant(RecognitionPeriod period, BaseEntity participant)`

Returns: RecognitionPeriodResult

Finds a specific participant's result for a recognition period.

Parameter	Description
`period`	the period to find the result within
`participant`	the participant to find the result for

`findClosedPeriods(RecognitionTopic topic, BaseEntity participant)`

Returns: RecognitionPeriod

Finds the first closed period of a topic (one with a processed date) whose promotion has started and for which the given participant is eligible.

Parameter	Description
`topic`	the topic to find a closed period within
`participant`	the participant to check eligibility for

`findAllClosedPeriods(RecognitionTopic topic, BaseEntity participant)`

Returns: List<RecognitionPeriod>

Finds every closed period of a topic (one with a processed date) whose promotion has started and for which the given participant is eligible.

Parameter	Description
`topic`	the topic to find closed periods within
`participant`	the participant to check eligibility for

`findAllPublishedPeriods(RecognitionTopic topic, BaseEntity participant)`

Returns: List<RecognitionPeriod>

Finds every open, published period of a topic for which the given participant is eligible. Closed periods are excluded.

Parameter	Description
`topic`	the topic to find published periods within
`participant`	the participant to check eligibility for

`findAllPublishedPeriods(RecognitionTopic topic, BaseEntity participant, Boolean excludeClosedPeriod)`

Returns: List<RecognitionPeriod>

Finds every published period of a topic for which the given participant is eligible.

Parameter	Description
`topic`	the topic to find published periods within
`participant`	the participant to check eligibility for
`excludeClosedPeriod`	if true, closed periods are excluded; defaults to true if null

`findPeriodsForParticipant(RecognitionTopic topic, BaseEntity participant)`

Returns: List<RecognitionPeriod>

Finds every active period of a topic for which the given participant is eligible.

Parameter	Description
`topic`	the topic to find periods within
`participant`	the participant to check eligibility for

`findPeriod(RecognitionTopic topic, BaseEntity participant, Date now)`

Returns: RecognitionPeriod

Finds the single active period of a topic that covers the given date and for which the given participant is eligible. Multiple overlapping periods are technically possible but would be a configuration error - there should only ever be one active period for a given participant and topic at a given date.

Parameter	Description
`topic`	the topic to find a period within
`participant`	the participant to check eligibility for
`now`	the date the period must cover

`findPeriodProjectedResult(RecognitionPeriod period, BaseEntity participant, Date now, BigDecimal actualValue)`

Returns: PeriodProjectedResult

Builds a projected-result helper for a participant in a period, used to project their final value and level from their actual value so far and the proportion of the period elapsed.

Parameter	Description
`period`	the period to project a result for
`participant`	the participant to project a result for
`now`	the date to calculate elapsed proportion from
`actualValue`	the participant's actual value so far in the period

`createBadge(RecognitionTopic topic, String badgeName, String badgeTitle)`

Returns: RecognitionBadge

Creates a badge in a topic.

Parameter	Description
`topic`	the topic to create the badge in
`badgeName`	the unique, path-safe name for the badge
`badgeTitle`	the display title for the badge

`updateBaseRecognition(BaseRecognition baseRecognition)`

Returns: void

Saves changes to a recognition (level or badge).

Parameter	Description
`baseRecognition`	the recognition to save

`newTopicBuilder(String name, String title)`

Returns: RecognitionTopicBuilder

Creates a new RecognitionTopicBuilder which can be used to create a recognition topic

Parameter	Description
`name`	the name of the topic as a {@code String}
`title`	the title of the topic as a {@code String}

`newBadgeBuilder(RecognitionTopic topic, String name)`

Returns: RecognitionBadgeBuilder

Creates a new RecognitionBadgeBuilder which can be used to create a recognition badge

Parameter	Description
`topic`	the topic to which the badge belongs as a {@code RecognitionTopic}
`name`	the name of the badge as a {@code String}

`deleteRecognitionPeriod(RecognitionPeriod period)`

Returns: void

Soft deletes the given recognition period

Parameter	Description
`period`	{@code RecognitionPeriod} to be deleted

To get full access to the Kademi Hub existing customers can login here, or new customers can register here.