To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Owns the persistence and calculation logic for Kademi's recognition domain: topics, levels, badges, periods, awards and points. This is the internal engine behind the recognitionManager JS service (RecognitionManager) - callers create and delete topics, levels and badges, scan a participant's progress against a topic's levels, calculate the points a level or badge is worth, and close out a period's results into real reward grants. Most of the underlying lookup and calculation work is delegated to a RecognitionHelper and a RecognitionLevelService held internally.
Properties
| Property | Returns | Description |
|---|---|---|
| allRecognitionPointsRuleTypes | List<RecognitionPointsRuleType> | All recognition points rule types registered in the account. A points rule type is a pluggable calculation strategy that can be assigned to a level or badge instead of a plain fixed points amount. |
| allTopics | List<RecognitionTopic> | All the recognition topics defined for the current admin organisation. |
| recognitionLevelService | RecognitionLevelService | The underlying RecognitionLevelService, which owns level award creation, points reconciliation and dry-run preview generation. Exposed for callers, such as RecognitionManager, that need its dry-run preview methods directly rather than going through this service. |
Methods
getRecognitionLevelService() · closePeriod(RecognitionPeriod period) · getAllRecognitionPointsRuleTypes() · findRuleType(String id) · findPeriodForDate(RecognitionTopic topic, Date now, BaseEntity participant) · findAllPeriodsForDate(RecognitionTopic topic, Date now) · getHighestLevelAward(String topic) · getNextHighestLevelAward(String topicName) · getLevelStatus(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext) · getLevelStatus(String topicName, CalcContext calcContext) · findAward(Organisation adminDomain, BaseRecognition recog, BaseEntity awardToEntity) · getHighestLevelAward(String topicName, BaseEntity participant) · getAwardedBadges(String topicName) · getAwardedBadges(String topicName, BaseEntity participant) · getAllTopics() · getTopic(String topicName) · getTopic(Long topicId) · createTopic(String topicName, String topicTitle) · deleteTopic(String topicName) · deleteTopic(Long topicId) · createBadge(String topicName, String badgeName, String badgeTitle) · createBadge(Long topicId, String badgeName, String badgeTitle) · createBadge(RecognitionTopic topic, String badgeName, String badgeTitle) · deleteBadge(RecognitionTopic topic, String badgeName) · deleteBadge(RecognitionTopic topic, Long badgeId) · deleteBadge(RecognitionTopic topic, RecognitionBadge badge) · createLevel(String topicName, String levelName, String levelTitle, BigDecimal levelAmount) · createLevel(Long topicId, String levelName, String levelTitle, BigDecimal levelAmount) · createLevel(RecognitionTopic topic, String levelName, String levelTitle, BigDecimal levelAmount) · deleteLevel(RecognitionTopic topic, String levelName) · deleteLevel(RecognitionTopic topic, Long levelId) · deleteLevel(RecognitionTopic topic, RecognitionLevel level) · createAward(BaseRecognition recognition, BaseEntity awardedTo) · createAward(BaseRecognition recognition, BaseEntity awardedTo, Date createdDate) · deleteAward(Long awardId) · getRecognitionAwards(ProfileBean profileBean) · getRecognitionAwards(UserResource userResource) · getRecognitionAwards(BaseEntity baseEntity) · findParticipants(RecognitionPeriod period) · findParticipants(RecognitionTopic topic) · scanLevels(RecognitionTopic topic, CalcContext calcContext) · scanLevels(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext) · scanLevels(RecognitionPeriod period, RecognitionTopic topic, BaseEntity participant, CalcContext calcContext) · calcCurrentValue(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext) · calcCurrentValueForPeriod(RecognitionTopic topic, BaseEntity participant, Date startDate, Date endDate, CalcContext calcContext) · calcPoints(BaseRecognition recognition, RecognitionAward award, RecognitionPeriodResult result) · calcPoints(BaseRecognition recognition, RecognitionAward award, RecognitionPeriodResult result, Narrative narrative) · calcLevelPointsPreview(RecognitionTopic topic, RecognitionLevel level, BaseEntity participant, RecognitionPeriod period, BigDecimal currentVal, Narrative n) · parsePointsRuleConfig(BaseRecognition recognition) · getHighestLevelAward(RecognitionTopic topic, BaseEntity participant) · findParticipants(BaseEntity entity, RecognitionTopic topic) · findParticipants(BaseEntity entity, RecognitionPeriod period) · findLevelAmountForParticipant(RecognitionLevel level, BaseEntity participant) · findLevelAmountForParticipant(RecognitionPeriod period, RecognitionLevel level, BaseEntity participant) · updateRankings(RecognitionPeriod period) · isElligibleNonPeriodic(RecognitionTopic topic, BaseEntity participant)
getRecognitionLevelService()
Returns: RecognitionLevelService
The underlying RecognitionLevelService, which owns level award creation, points reconciliation and dry-run preview generation. Exposed for callers, such as RecognitionManager, that need its dry-run preview methods directly rather than going through this service.
closePeriod(RecognitionPeriod period)
Returns: void
Closes a recognition period, finalising its results into real points and rewards. For a continuous-points topic this tops up whatever has already been credited incrementally during the period so the running total matches the final calculated entitlement; for a topic that awards points on reaching a level, this issues the outstanding points for each participant's period result, netting off anything already issued. Dry-run topics have nothing real to close and return immediately. Closing is one-way - refuses to run if any level configured to award points has no points bucket, or if the period has no calculated results yet, since either case would finalise the period having quietly awarded nobody anything.
| Parameter | Description |
|---|---|
period | the period to close |
getAllRecognitionPointsRuleTypes()
Returns: List<RecognitionPointsRuleType>
All recognition points rule types registered in the account. A points rule type is a pluggable calculation strategy that can be assigned to a level or badge instead of a plain fixed points amount.
findRuleType(String id)
Returns: RecognitionPointsRuleType
Finds a registered recognition points rule type by its id.
| Parameter | Description |
|---|---|
id | the rule type's id |
findPeriodForDate(RecognitionTopic topic, Date now, BaseEntity participant)
Returns: RecognitionPeriod
Finds the period of a periodic topic that covers the given date for a participant.
| Parameter | Description |
|---|---|
topic | the recognition topic |
now | the date to find the covering period for |
participant | the participant whose period is being looked up |
findAllPeriodsForDate(RecognitionTopic topic, Date now)
Returns: List<RecognitionPeriod>
Finds every period of a periodic topic that covers the given date, across all participants.
| Parameter | Description |
|---|---|
topic | the recognition topic |
now | the date to find the covering periods for |
getHighestLevelAward(String topic)
Returns: RecognitionAward
The highest level award currently held by the current user in the named topic.
| Parameter | Description |
|---|---|
topic | the name of the recognition topic |
getNextHighestLevelAward(String topicName)
Returns: RecognitionLevel
The next level the current user has not yet reached in the named topic, above whatever level they currently hold.
| Parameter | Description |
|---|---|
topicName | the name of the recognition topic |
getLevelStatus(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)
Returns: LevelStatus
Calculates a participant's progress through a topic's levels: their current level, the next level to reach, and how far through the gap between them their current value sits, as a percentage. Returns null if the topic or participant is null, or if calculation fails for any reason - the failure is logged rather than propagated.
| Parameter | Description |
|---|---|
topic | the recognition topic to calculate progress for |
participant | the participant to calculate progress for |
calcContext | calculation context used and populated while resolving the participant's current value |
getLevelStatus(String topicName, CalcContext calcContext)
Returns: LevelStatus
As the RecognitionTopic-based overload of getLevelStatus, but looks up the topic by name and calculates progress for the current user.
| Parameter | Description |
|---|---|
topicName | the name of the recognition topic |
calcContext | calculation context used and populated while resolving the current user's current value |
findAward(Organisation adminDomain, BaseRecognition recog, BaseEntity awardToEntity)
Returns: RecognitionAward
Finds an existing, non-deleted award of the given recognition (level or badge) held by an entity.
| Parameter | Description |
|---|---|
adminDomain | the account the award belongs to |
recog | the recognition (level or badge) to look for |
awardToEntity | the profile or organisation to look for the award on |
getHighestLevelAward(String topicName, BaseEntity participant)
Returns: RecognitionAward
The highest level award currently held by a participant in the named topic.
| Parameter | Description |
|---|---|
topicName | the name of the recognition topic |
participant | the participant to look up |
getAwardedBadges(String topicName)
Returns: List<RecognitionAward>
The badge awards held by the current user in the named topic.
| Parameter | Description |
|---|---|
topicName | the name of the recognition topic |
getAwardedBadges(String topicName, BaseEntity participant)
Returns: List<RecognitionAward>
The badge awards held by a participant in the named topic.
| Parameter | Description |
|---|---|
topicName | the name of the recognition topic |
participant | the participant to look up |
getAllTopics()
Returns: List<RecognitionTopic>
All the recognition topics defined for the current admin organisation.
getTopic(String topicName)
Returns: RecognitionTopic
Finds a recognition topic in the current admin organisation by its name.
| Parameter | Description |
|---|---|
topicName | the name of the topic, required |
getTopic(Long topicId)
Returns: RecognitionTopic
Finds a recognition topic in the current admin organisation by its id.
| Parameter | Description |
|---|---|
topicId | the id of the topic, required |
createTopic(String topicName, String topicTitle)
Returns: RecognitionTopic
Creates a new recognition topic in the current admin organisation.
| Parameter | Description |
|---|---|
topicName | the topic's name, required |
topicTitle | the topic's display title, required |
deleteTopic(String topicName)
Returns: void
Deletes a topic by its name
| Parameter | Description |
|---|---|
topicName | the name of the topic. REQUIRED |
deleteTopic(Long topicId)
Returns: void
Deletes a topic by its id
| Parameter | Description |
|---|---|
topicId | the id of the topic. REQUIRED |
createBadge(String topicName, String badgeName, String badgeTitle)
Returns: RecognitionBadge
Creates a new badge on the named topic.
| Parameter | Description |
|---|---|
topicName | the name of the topic to add the badge to |
badgeName | the badge's name, required |
badgeTitle | the badge's display title, required |
createBadge(Long topicId, String badgeName, String badgeTitle)
Returns: RecognitionBadge
Creates a new badge on the topic with the given id.
| Parameter | Description |
|---|---|
topicId | the id of the topic to add the badge to |
badgeName | the badge's name, required |
badgeTitle | the badge's display title, required |
createBadge(RecognitionTopic topic, String badgeName, String badgeTitle)
Returns: RecognitionBadge
Creates a new badge on a topic.
| Parameter | Description |
|---|---|
topic | the topic to add the badge to |
badgeName | the badge's name, required |
badgeTitle | the badge's display title, required |
deleteBadge(RecognitionTopic topic, String badgeName)
Returns: void
Removes a badge from a topic by its name. Does nothing if the topic is null or the badge name is blank.
| Parameter | Description |
|---|---|
topic | the topic to remove the badge from |
badgeName | the name of the badge to remove |
deleteBadge(RecognitionTopic topic, Long badgeId)
Returns: void
Removes a badge from a topic by its id. Does nothing if the topic is null.
| Parameter | Description |
|---|---|
topic | the topic to remove the badge from |
badgeId | the id of the badge to remove |
deleteBadge(RecognitionTopic topic, RecognitionBadge badge)
Returns: void
Removes a badge from a topic. Does nothing if either argument is null.
| Parameter | Description |
|---|---|
topic | the topic to remove the badge from |
badge | the badge to remove |
createLevel(String topicName, String levelName, String levelTitle, BigDecimal levelAmount)
Returns: RecognitionLevel
Creates a new level on the named topic.
| Parameter | Description |
|---|---|
topicName | the name of the topic to add the level to |
levelName | the level's name, required |
levelTitle | the level's display title, required |
levelAmount | the metric value at which this level is reached |
createLevel(Long topicId, String levelName, String levelTitle, BigDecimal levelAmount)
Returns: RecognitionLevel
Creates a new level on the topic with the given id.
| Parameter | Description |
|---|---|
topicId | the id of the topic to add the level to |
levelName | the level's name, required |
levelTitle | the level's display title, required |
levelAmount | the metric value at which this level is reached |
createLevel(RecognitionTopic topic, String levelName, String levelTitle, BigDecimal levelAmount)
Returns: RecognitionLevel
Creates a new level on a topic.
| Parameter | Description |
|---|---|
topic | the topic to add the level to |
levelName | the level's name, required |
levelTitle | the level's display title, required |
levelAmount | the metric value at which this level is reached |
deleteLevel(RecognitionTopic topic, String levelName)
Returns: void
Removes a level from a topic by its name. Does nothing if the topic is null or the level name is blank.
| Parameter | Description |
|---|---|
topic | the topic to remove the level from |
levelName | the name of the level to remove |
deleteLevel(RecognitionTopic topic, Long levelId)
Returns: void
Removes a level from a topic by its id. Does nothing if the topic is null.
| Parameter | Description |
|---|---|
topic | the topic to remove the level from |
levelId | the id of the level to remove |
deleteLevel(RecognitionTopic topic, RecognitionLevel level)
Returns: void
Removes a level from a topic. Does nothing if either argument is null.
| Parameter | Description |
|---|---|
topic | the topic to remove the level from |
level | the level to remove |
createAward(BaseRecognition recognition, BaseEntity awardedTo)
Returns: RecognitionAward
Awards a recognition (level or badge) to an entity, dated now.
| Parameter | Description |
|---|---|
recognition | the recognition being awarded, i.e. a level or badge |
awardedTo | who this is awarded to, i.e. a profile or an organisation |
createAward(BaseRecognition recognition, BaseEntity awardedTo, Date createdDate)
Returns: RecognitionAward
Awards a recognition (level or badge) to an entity on a specific date. Resolves the entity's period result for the award date, if the recognition's topic is periodic, and runs any deferred actions the level service queues up as a result of the award (such as reward grants) once it has been created.
| Parameter | Description |
|---|---|
recognition | the recognition being awarded, i.e. a level or badge |
awardedTo | who this is awarded to, i.e. a profile or an organisation |
createdDate | the date this award was awarded |
deleteAward(Long awardId)
Returns: void
Deletes an award by its id, provided it belongs to the current admin organisation. Does nothing if no award exists with that id, or if it belongs to a different organisation.
| Parameter | Description |
|---|---|
awardId | the id of the award to delete |
getRecognitionAwards(ProfileBean profileBean)
Returns: List<RecognitionAward>
All recognition awards held by a profile, from all topics and periods.
| Parameter | Description |
|---|---|
profileBean | the profile to look up awards for |
getRecognitionAwards(UserResource userResource)
Returns: List<RecognitionAward>
All recognition awards held by a user, from all topics and periods.
| Parameter | Description |
|---|---|
userResource | the user resource to look up awards for |
getRecognitionAwards(BaseEntity baseEntity)
Returns: List<RecognitionAward>
All recognition awards held by an entity, from all topics and periods.
| Parameter | Description |
|---|---|
baseEntity | the profile or organisation to look up awards for |
findParticipants(RecognitionPeriod period)
Returns: Collection<? extends BaseEntity>
Finds the entities participating in a period's promotion, resolved from the promotions manager based on whether the topic is organisation or profile based.
| Parameter | Description |
|---|---|
period | the period to find participants for |
findParticipants(RecognitionTopic topic)
Returns: Collection<? extends BaseEntity>
Finds the entities eligible to participate in a topic, resolved according to how the topic's value is calculated: from the sales data series' group, from the groups configured on the topic's points bucket, or otherwise from the topic's participant selectors.
| Parameter | Description |
|---|---|
topic | the recognition topic to find participants for |
scanLevels(RecognitionTopic topic, CalcContext calcContext)
Returns: void
Scans the current user's progress against a topic's levels and creates or removes level awards as needed. Delegates to the periodic or open-dates scanner depending on whether the topic is periodic.
| Parameter | Description |
|---|---|
topic | the recognition topic to scan |
calcContext | calculation context used and populated while resolving the current value |
scanLevels(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)
Returns: void
Scans a participant's progress against a topic's levels and creates or removes level awards as needed. This is the main entry point for recognition level scanning - it is called whenever data that could change a participant's calculated value changes (sales records, points grants, module progress, and so on) and by the periodic recognition scan job. Does nothing if the participant is not eligible to participate in the topic. Delegates to the periodic or open-dates scanner depending on whether the topic is periodic.
| Parameter | Description |
|---|---|
topic | the recognition topic to scan |
participant | the participant to scan |
calcContext | calculation context used and populated while resolving the current value |
scanLevels(RecognitionPeriod period, RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)
Returns: void
Scans a participant's progress against a topic's levels within a specific period, and creates or removes level awards as needed. Only valid for a periodic topic.
| Parameter | Description |
|---|---|
period | the period to scan within |
topic | the recognition topic to scan, must be periodic |
participant | the participant to scan |
calcContext | calculation context used and populated while resolving the current value |
calcCurrentValue(RecognitionTopic topic, BaseEntity participant, CalcContext calcContext)
Returns: BigDecimal
Calculates a participant's current value for a topic - the number against which its levels are compared - according to however the topic is configured to source its value (sales data, points, elearning modules or a metric).
| Parameter | Description |
|---|---|
topic | the recognition topic to calculate a value for |
participant | the participant to calculate the value for |
calcContext | calculation context used and populated while calculating |
calcCurrentValueForPeriod(RecognitionTopic topic, BaseEntity participant, Date startDate, Date endDate, CalcContext calcContext)
Returns: BigDecimal
As calcCurrentValue, but restricted to a specific date range rather than the topic's whole history.
| Parameter | Description |
|---|---|
topic | the recognition topic to calculate a value for |
participant | the participant to calculate the value for |
startDate | the start of the date range to calculate over |
endDate | the end of the date range to calculate over |
calcContext | calculation context used and populated while calculating |
calcPoints(BaseRecognition recognition, RecognitionAward award, RecognitionPeriodResult result)
Returns: Double
Calculates the points a recognition (level or badge) is worth, dispatching to its configured points rule type if one is set, falling back to its plain numPoints otherwise. This is the same calculation used when a real award is reconciled, so callers previewing points for display get a value consistent with what would actually be awarded.
| Parameter | Description |
|---|---|
recognition | the level or badge to calculate points for |
award | an existing award to calculate from, or null if none exists yet (some rule types fall back to plain numPoints without one) |
result | the period result to calculate from, for period-aware rule types, or null for a non-periodic topic |
calcPoints(BaseRecognition recognition, RecognitionAward award, RecognitionPeriodResult result, Narrative narrative)
Returns: Double
As the three-argument overload, but appends an explanation of how the points were calculated to the given narrative.
| Parameter | Description |
|---|---|
recognition | the level or badge to calculate points for |
award | an existing award to calculate from, or null if none exists yet |
result | the period result to calculate from, for period-aware rule types, or null for a non-periodic topic |
narrative | narrative to append the calculation explanation to |
calcLevelPointsPreview(RecognitionTopic topic, RecognitionLevel level, BaseEntity participant, RecognitionPeriod period, BigDecimal currentVal, Narrative n)
Returns: Pair<BigDecimal,BigDecimal>
Previews what a participant would be awarded for a level without creating a real award: the points that would be granted, and the level's threshold value. Builds a throwaway award and, for a periodic topic, a throwaway period result to run the normal points calculation against, so the preview reflects the same rule-type logic a real award would use.
| Parameter | Description |
|---|---|
topic | the recognition topic the level belongs to |
level | the level to preview |
participant | the participant to preview the award for |
period | the period to preview within, for a periodic topic, or null otherwise |
currentVal | the participant's current calculated value, used to decide whether they are within the level |
n | narrative to append the calculation explanation to, or null to skip narration |
parsePointsRuleConfig(BaseRecognition recognition)
Returns: Map<String,String>
Parses a recognition's stored points rule configuration into a map of parameter name to value, for display or editing.
| Parameter | Description |
|---|---|
recognition | the level or badge whose points rule configuration is being parsed |
getHighestLevelAward(RecognitionTopic topic, BaseEntity participant)
Returns: RecognitionAward
The highest level award currently held by a participant in a topic, resolved within the topic's current period.
| Parameter | Description |
|---|---|
topic | the recognition topic |
participant | the participant to look up |
findParticipants(BaseEntity entity, RecognitionTopic topic)
Returns: List<? extends BaseEntity>
For a given user, finds all participants for a topic: if the topic is profile based, just the user; if it is organisation based, each organisation associated with the user that matches the topic's configured organisation type (or every organisation of the entity, if the topic has no participant selector configured).
| Parameter | Description |
|---|---|
entity | the user or organisation to find participants for |
topic | the recognition topic |
findParticipants(BaseEntity entity, RecognitionPeriod period)
Returns: List<? extends BaseEntity>
As findParticipants(BaseEntity, RecognitionTopic), but scoped to a period's promotion: only organisations or profiles eligible to participate in the period's promotion are returned.
| Parameter | Description |
|---|---|
entity | the user or organisation to find participants for |
period | the recognition period |
findLevelAmountForParticipant(RecognitionLevel level, BaseEntity participant)
Returns: BigDecimal
The threshold value a participant needs to reach a level, resolved within the level's topic's current period.
| Parameter | Description |
|---|---|
level | the recognition level |
participant | the participant to resolve the level amount for |
findLevelAmountForParticipant(RecognitionPeriod period, RecognitionLevel level, BaseEntity participant)
Returns: BigDecimal
As the two-argument overload, but resolved within a specific period rather than the current one.
| Parameter | Description |
|---|---|
period | the period to resolve the level amount within, or null for a non-periodic topic |
level | the recognition level |
participant | the participant to resolve the level amount for |
updateRankings(RecognitionPeriod period)
Returns: void
Ranks a period's results by achieved value and marks the period as published. Participants with equal achieved values share the same rank; the next distinct value's rank is the count of participants ranked before it. Runs at the end of a recognition scan for a periodic topic.
| Parameter | Description |
|---|---|
period | the period to rank |
isElligibleNonPeriodic(RecognitionTopic topic, BaseEntity participant)
Returns: boolean
Whether an entity is eligible to participate in a non-periodic (open-dates) topic, based on the topic's group or organisation type selector and whether the entity is a profile or an organisation matching the topic's org/profile mode.
| Parameter | Description |
|---|---|
topic | the recognition topic |
participant | the entity to check eligibility for |
© 2025 Kademi Ltd