To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
A container for a set of recognition badges and levels within an organisation, and the metric its levels are measured against. A topic acts like a folder: every badge and level belongs to exactly one topic. Where the topic has levels, it also decides what a participant's value is measured from - a sales data series, a points bucket, an elearning path, or a named metric - and only one of those sources is used. The calc mode says whether levels are worked out automatically by the nightly scan, as a dry run, or only by hand, and the regression mode says whether a participant can lose a level again. Deleting a topic is a soft delete, recorded by deletedBy and deletedDate, so lookups filter deleted topics out rather than removing the row.
Group: Database Entities
Implements: Serializable, Relational
Properties
| Property | Returns | Description |
|---|---|---|
| achievedLevelRenotifyHours | Integer | Do not generate another achieved-level notification for the same participant and level within this many hours. |
| achievedLevelSettleMins | Integer | How long, in minutes, to wait after a participant achieves a level before firing the notification. While this settle period runs, further level changes just re-point the pending notification, so only the final level is notified. |
| allAwards | List<RecognitionAward> | Every award ever made from this topic, across all its badges and levels. Despite the get prefix this reads from the database on the current session each time it is called, so it is expensive on a busy topic. |
| autoCalc | boolean | Whether levels are calculated and awarded automatically by the nightly scan, ie the calc mode is auto. |
| badges | List<RecognitionBadge> | The badges belonging to this topic, in the order the recognitions are held. Built from the topic's recognitions each time it is called; levels are left out. Empty if the topic has no badges. |
| calcMode | String | How levels are worked out for this topic: auto for the nightly scan to award them, dry-run to calculate them without awarding anything, and an empty string for manual, where levels are only awarded by hand. |
| closeToLevelPercent | BigDecimal | The percentage of progress towards the next level at which a close-to-level notification should be generated, eg 90 means notify at 90% of the way to the next level. |
| closeToLevelRenotifyHours | Integer | Do not generate another close-to-level notification for the same participant and level within this many hours. |
| closeToLevelSettleMins | Integer | How long, in minutes, to wait after detecting that a participant is close to a level before firing the notification. This settle period allows a real level achievement to land first, so we dont notify someone who is just about to reach the level anyway. |
| dataSeries | SalesDataSeries | The sales data series a participant's level value is measured from, when the topic is driven by sales data. Only one of the data series, points bucket, elearning path and metric id sources is used by a topic, so this is null unless the topic is measured on sales. |
| dateMode | String | Whether the topic is divided into periods. The value periodic means levels are calculated per recognition period; null means the topic has no periods and runs continuously. |
| deletedBy | Profile | The profile which soft deleted this topic. Non-null only for a deleted topic, and its presence is what the lookups on this class use to filter deleted topics out. |
| deletedDate | Date | When this topic was soft deleted. Null for a topic which is not deleted. |
| dryRun | boolean | Whether levels are calculated but nothing is actually awarded, ie the calc mode is dry-run. Useful for checking a new topic's thresholds before it goes live. |
| elearningPath | String | The path of the programme, course or module a participant's level value is measured from, when the topic is driven by elearning progress. Only one measurement source is used by a topic, so this is null unless the topic is measured on elearning. |
| id | long | Database identifier for this topic, assigned when it is first saved. |
| lastScan | Date | When the automatic level scan last ran over this topic. The scan picks up auto calc topics which have not been scanned in the last day, so a null here means the topic has never been scanned and is due immediately. |
| levelPointsMode | String | When points attached to a level are awarded. The value continuous awards them progressively within the tier and reconciles them on every check; null awards them once, when the level is reached. |
| levelPointsModeContinuous | boolean | Whether level points are awarded progressively within a tier and reconciled on every check, ie the level points mode is continuous, rather than being awarded once when the level is reached. |
| levelRegressionEnabled | boolean | Whether participants can drop back down a level, ie the regression mode is one of the bi-directional values. |
| levelRegressionLosePoints | boolean | Whether losing a level also deducts the points that were awarded for reaching it, ie the regression mode is bi-lose-points. |
| levels | List<RecognitionLevel> | The levels belonging to this topic, sorted ascending on their level amount so the lowest tier comes first. Built from the topic's recognitions each time it is called; badges are left out. Empty if the topic has no levels. |
| metricId | String | Identifies the metric used to calculate a participant's value, when the topic is driven by a metric rather than by sales, points or elearning. Only one measurement source is used by a topic, so this is null unless the topic is measured on a metric. |
| name | String | Portable, path-safe identifier for this topic, unique within the organisation and used as the lookup key and as a path segment. Use the title for anything shown to users. Never null for a persisted topic. |
| notifyAchievedLevel | Boolean | If true, a RecognitionLevelAchievedEvent is fired once a participant's achieved level has settled, for the level they settled on. Unlike the per-award RecognitionEvent, only one of these fires when several levels are passed through in quick succession. Defaults to false. |
| notifyCloseToLevel | Boolean | If true, a RecognitionCloseToLevelEvent is fired when a participant gets within the close-to-level percentage of the next level threshold. Defaults to false. |
| orgLevelAwards | Boolean | If true, awards from this topic are given to organisations rather than to individual profiles, which only makes sense where the points bucket or data series behind the topic attributes value to organisations. Defaults to false. |
| orgLevels | boolean | Whether this topic makes awards at organisation level, ie the org level awards flag treated as false when it has never been set. |
| participantSelectors | String | Which profiles take part in this topic, as a selector expression naming included and excluded groups, org types and so on. Null or blank means everyone in the organisation takes part. |
| periodic | boolean | Whether this topic is divided into recognition periods, ie the date mode is periodic. |
| pointsBucket | Reward | The points bucket a participant's level value is measured from, when the topic is driven by points. Only one of the data series, points bucket, elearning path and metric id sources is used by a topic, so this is null unless the topic is measured on points. |
| recognitions | List<BaseRecognition> | Every badge and level belonging to this topic, in no particular order. Use getLevels or getBadges for just one kind. Can be null on a topic which has never had a recognition added. |
| regressionMode | String | Whether a participant can drop back down a level again. Null means levels only ever go up; bi means they can go both ways; bi-lose-points means they can go both ways and points awarded for the lost level are deducted. |
| startDate | Date | If provided, only sales or points since this date are counted towards the current level, so earlier history is ignored. Null means all history counts. |
| title | String | Free-text display label for this topic, entered by an administrator. Not unique and not path-safe, so never use it as an identifier; use the name for that. Never null for a persisted topic. |
Methods
getName() · setName(String name) · getId() · getTitle() · setTitle(String title) · setOrganisation(Organisation organisation) · getDataSeries() · setDataSeries(SalesDataSeries dataSeries) · getPointsBucket() · setPointsBucket(Reward pointsBucket) · getStartDate() · setStartDate(Date startDate) · getDateMode() · setDateMode(String dateMode) · getRecognitions() · setRecognitions(List<BaseRecognition> recognitions) · getDeletedBy() · setDeletedBy(Profile deletedBy) · getDeletedDate() · setDeletedDate(Date deletedDate) · getLastScan() · setLastScan(Date lastScan) · getNotifyCloseToLevel() · setNotifyCloseToLevel(Boolean notifyCloseToLevel) · getCloseToLevelPercent() · setCloseToLevelPercent(BigDecimal closeToLevelPercent) · getCloseToLevelSettleMins() · setCloseToLevelSettleMins(Integer closeToLevelSettleMins) · getCloseToLevelRenotifyHours() · setCloseToLevelRenotifyHours(Integer closeToLevelRenotifyHours) · getNotifyAchievedLevel() · setNotifyAchievedLevel(Boolean notifyAchievedLevel) · getAchievedLevelSettleMins() · setAchievedLevelSettleMins(Integer achievedLevelSettleMins) · getAchievedLevelRenotifyHours() · setAchievedLevelRenotifyHours(Integer achievedLevelRenotifyHours) · getOrgLevelAwards() · setOrgLevelAwards(Boolean orgLevelAwards) · getParticipantSelectors() · setParticipantSelectors(String participantSelectors) · getRegressionMode() · setRegressionMode(String regressionMode) · getCalcMode() · setCalcMode(String calcMode) · getLevelPointsMode() · setLevelPointsMode(String levelPointsMode) · getElearningPath() · setElearningPath(String elearningPath) · getMetricId() · setMetricId(String metricId) · getLevels() · getLevel(String levelName) · getLevel(Long id) · getBadges() · getBadge(String badgeName) · getRecognition(String name) · getBadge(Long id) · getAllAwards() · isOrgLevels() · isLevelRegressionEnabled() · isLevelRegressionLosePoints() · isApplicableForLevels(BaseEntity entity) · isAutoCalc() · isDryRun() · isLevelPointsModeContinuous() · findPeriods() · isPeriodic() · findPeriodsForDate(Date now) · findPeriod(Long periodId) · rowId()
getName()
Returns: String
Portable, path-safe identifier for this topic, unique within the organisation and used as the lookup key and as a path segment. Use the title for anything shown to users. Never null for a persisted topic.
setName(String name)
Returns: void
Sets the path-safe identifier for this topic. Must be unique within the organisation, since lookups by name expect a single match.
| Parameter | Description |
|---|---|
name | the name to set |
getId()
Returns: long
Database identifier for this topic, assigned when it is first saved.
getTitle()
Returns: String
Free-text display label for this topic, entered by an administrator. Not unique and not path-safe, so never use it as an identifier; use the name for that. Never null for a persisted topic.
setTitle(String title)
Returns: void
Sets the free-text display label shown to users.
| Parameter | Description |
|---|---|
title | the display title to set |
setOrganisation(Organisation organisation)
Returns: void
Sets the organisation which owns this topic.
| Parameter | Description |
|---|---|
organisation | the owning organisation |
getDataSeries()
Returns: SalesDataSeries
The sales data series a participant's level value is measured from, when the topic is driven by sales data. Only one of the data series, points bucket, elearning path and metric id sources is used by a topic, so this is null unless the topic is measured on sales.
setDataSeries(SalesDataSeries dataSeries)
Returns: void
Measures this topic's levels against a sales data series. Only one measurement source should be set on a topic.
| Parameter | Description |
|---|---|
dataSeries | the sales data series to measure against, or null for none |
getPointsBucket()
Returns: Reward
The points bucket a participant's level value is measured from, when the topic is driven by points. Only one of the data series, points bucket, elearning path and metric id sources is used by a topic, so this is null unless the topic is measured on points.
setPointsBucket(Reward pointsBucket)
Returns: void
Measures this topic's levels against a points bucket. Only one measurement source should be set on a topic.
| Parameter | Description |
|---|---|
pointsBucket | the points bucket to measure against, or null for none |
getStartDate()
Returns: Date
If provided, only sales or points since this date are counted towards the current level, so earlier history is ignored. Null means all history counts.
setStartDate(Date startDate)
Returns: void
Sets the date from which sales or points are counted towards a level.
| Parameter | Description |
|---|---|
startDate | the date to count from, or null to count all history |
getDateMode()
Returns: String
Whether the topic is divided into periods. The value periodic means levels are calculated per recognition period; null means the topic has no periods and runs continuously.
setDateMode(String dateMode)
Returns: void
Sets whether the topic runs in periods. Pass periodic to divide it into recognition periods, or null for a continuous topic.
| Parameter | Description |
|---|---|
dateMode | the date mode to set, or null for no periods |
getRecognitions()
Returns: List<BaseRecognition>
Every badge and level belonging to this topic, in no particular order. Use getLevels or getBadges for just one kind. Can be null on a topic which has never had a recognition added.
setRecognitions(List<BaseRecognition> recognitions)
Returns: void
Replaces the collection of badges and levels held against this topic. Prefer addLevel, addBadge and removeRecognition, which also create or delete the underlying rows.
| Parameter | Description |
|---|---|
recognitions | the badges and levels to hold against this topic |
getDeletedBy()
Returns: Profile
The profile which soft deleted this topic. Non-null only for a deleted topic, and its presence is what the lookups on this class use to filter deleted topics out.
setDeletedBy(Profile deletedBy)
Returns: void
Records which profile deleted this topic. Setting it non-null is what marks the topic as deleted.
| Parameter | Description |
|---|---|
deletedBy | the deleting profile, or null to restore the topic |
getDeletedDate()
Returns: Date
When this topic was soft deleted. Null for a topic which is not deleted.
setDeletedDate(Date deletedDate)
Returns: void
Records when this topic was deleted.
| Parameter | Description |
|---|---|
deletedDate | the deletion timestamp, or null to restore the topic |
getLastScan()
Returns: Date
When the automatic level scan last ran over this topic. The scan picks up auto calc topics which have not been scanned in the last day, so a null here means the topic has never been scanned and is due immediately.
setLastScan(Date lastScan)
Returns: void
Records when the automatic level scan last ran over this topic, which is what stops it running again within the same day.
| Parameter | Description |
|---|---|
lastScan | the scan timestamp to record |
getNotifyCloseToLevel()
Returns: Boolean
If true, a RecognitionCloseToLevelEvent is fired when a participant gets within the close-to-level percentage of the next level threshold. Defaults to false.
setNotifyCloseToLevel(Boolean notifyCloseToLevel)
Returns: void
Turns close-to-level notifications on or off for this topic.
| Parameter | Description |
|---|---|
notifyCloseToLevel | true to enable close-to-level notifications |
getCloseToLevelPercent()
Returns: BigDecimal
The percentage of progress towards the next level at which a close-to-level notification should be generated, eg 90 means notify at 90% of the way to the next level.
setCloseToLevelPercent(BigDecimal closeToLevelPercent)
Returns: void
Sets how far through the progress to the next level a participant must be before a close-to-level notification is generated, as a percentage, so 90 means notify at 90 percent of the way there.
| Parameter | Description |
|---|---|
closeToLevelPercent | the notification threshold as a percentage |
getCloseToLevelSettleMins()
Returns: Integer
How long, in minutes, to wait after detecting that a participant is close to a level before firing the notification. This settle period allows a real level achievement to land first, so we dont notify someone who is just about to reach the level anyway.
setCloseToLevelSettleMins(Integer closeToLevelSettleMins)
Returns: void
Sets how long, in minutes, to wait after detecting that a participant is close to a level before the notification fires.
| Parameter | Description |
|---|---|
closeToLevelSettleMins | the settle period in minutes |
getCloseToLevelRenotifyHours()
Returns: Integer
Do not generate another close-to-level notification for the same participant and level within this many hours.
setCloseToLevelRenotifyHours(Integer closeToLevelRenotifyHours)
Returns: void
Sets how many hours must pass before the same participant is notified again about the same level.
| Parameter | Description |
|---|---|
closeToLevelRenotifyHours | the re-notification cool-off in hours |
getNotifyAchievedLevel()
Returns: Boolean
If true, a RecognitionLevelAchievedEvent is fired once a participant's achieved level has settled, for the level they settled on. Unlike the per-award RecognitionEvent, only one of these fires when several levels are passed through in quick succession. Defaults to false.
setNotifyAchievedLevel(Boolean notifyAchievedLevel)
Returns: void
Turns settled achieved-level notifications on or off for this topic.
| Parameter | Description |
|---|---|
notifyAchievedLevel | true to enable achieved-level notifications |
getAchievedLevelSettleMins()
Returns: Integer
How long, in minutes, to wait after a participant achieves a level before firing the notification. While this settle period runs, further level changes just re-point the pending notification, so only the final level is notified.
setAchievedLevelSettleMins(Integer achievedLevelSettleMins)
Returns: void
Sets how long, in minutes, to wait after a participant achieves a level before the notification fires, so a run of level changes produces one notification for the level they settle on.
| Parameter | Description |
|---|---|
achievedLevelSettleMins | the settle period in minutes |
getAchievedLevelRenotifyHours()
Returns: Integer
Do not generate another achieved-level notification for the same participant and level within this many hours.
setAchievedLevelRenotifyHours(Integer achievedLevelRenotifyHours)
Returns: void
Sets how many hours must pass before the same participant is notified again about achieving the same level.
| Parameter | Description |
|---|---|
achievedLevelRenotifyHours | the re-notification cool-off in hours |
getOrgLevelAwards()
Returns: Boolean
If true, awards from this topic are given to organisations rather than to individual profiles, which only makes sense where the points bucket or data series behind the topic attributes value to organisations. Defaults to false.
setOrgLevelAwards(Boolean orgLevelAwards)
Returns: void
Sets whether awards from this topic go to organisations instead of individual profiles.
| Parameter | Description |
|---|---|
orgLevelAwards | true to make awards at organisation level |
getParticipantSelectors()
Returns: String
Which profiles take part in this topic, as a selector expression naming included and excluded groups, org types and so on. Null or blank means everyone in the organisation takes part.
setParticipantSelectors(String participantSelectors)
Returns: void
Sets which profiles take part in this topic, as a selector expression of included and excluded groups and org types.
| Parameter | Description |
|---|---|
participantSelectors | the participant selector expression, or null for everyone |
getRegressionMode()
Returns: String
Whether a participant can drop back down a level again. Null means levels only ever go up; bi means they can go both ways; bi-lose-points means they can go both ways and points awarded for the lost level are deducted.
setRegressionMode(String regressionMode)
Returns: void
Sets whether participants can drop back down a level, using one of the REGRESSION constants on this class, or null for levels which only ever go up.
| Parameter | Description |
|---|---|
regressionMode | the regression mode to set |
getCalcMode()
Returns: String
How levels are worked out for this topic: auto for the nightly scan to award them, dry-run to calculate them without awarding anything, and an empty string for manual, where levels are only awarded by hand.
setCalcMode(String calcMode)
Returns: void
Sets how levels are worked out, using one of the CALC_MODE constants on this class. Only topics in auto mode are picked up by the nightly scan.
| Parameter | Description |
|---|---|
calcMode | the calculation mode to set |
getLevelPointsMode()
Returns: String
When points attached to a level are awarded. The value continuous awards them progressively within the tier and reconciles them on every check; null awards them once, when the level is reached.
setLevelPointsMode(String levelPointsMode)
Returns: void
Sets when points attached to a level are awarded. Pass continuous to award them progressively within the tier, or null to award them only when the level is reached.
| Parameter | Description |
|---|---|
levelPointsMode | the level points mode to set |
getElearningPath()
Returns: String
The path of the programme, course or module a participant's level value is measured from, when the topic is driven by elearning progress. Only one measurement source is used by a topic, so this is null unless the topic is measured on elearning.
setElearningPath(String elearningPath)
Returns: void
Measures this topic's levels against a programme, course or module path. Only one measurement source should be set on a topic.
| Parameter | Description |
|---|---|
elearningPath | the elearning path to measure against, or null for none |
getMetricId()
Returns: String
Identifies the metric used to calculate a participant's value, when the topic is driven by a metric rather than by sales, points or elearning. Only one measurement source is used by a topic, so this is null unless the topic is measured on a metric.
setMetricId(String metricId)
Returns: void
Measures this topic's levels against a named metric. Only one measurement source should be set on a topic.
| Parameter | Description |
|---|---|
metricId | the metric identifier to measure against, or null for none |
getLevels()
Returns: List<RecognitionLevel>
The levels belonging to this topic, sorted ascending on their level amount so the lowest tier comes first. Built from the topic's recognitions each time it is called; badges are left out. Empty if the topic has no levels.
getLevel(String levelName)
Returns: RecognitionLevel
Finds one of this topic's levels by its name. Cheap, since it scans the levels already loaded with the topic.
| Parameter | Description |
|---|---|
levelName | the level's path-safe name |
getLevel(Long id)
Returns: RecognitionLevel
Finds one of this topic's levels by its database id, which also confirms the level belongs to this topic.
| Parameter | Description |
|---|---|
id | the level id, must not be null |
getBadges()
Returns: List<RecognitionBadge>
The badges belonging to this topic, in the order the recognitions are held. Built from the topic's recognitions each time it is called; levels are left out. Empty if the topic has no badges.
getBadge(String badgeName)
Returns: RecognitionBadge
Finds one of this topic's badges by its name. Cheap, since it scans the badges already loaded with the topic.
| Parameter | Description |
|---|---|
badgeName | the badge's path-safe name |
getRecognition(String name)
Returns: BaseRecognition
Finds a badge or level in this topic by name, without having to know which of the two it is. Names are unique within a topic, so at most one is returned.
| Parameter | Description |
|---|---|
name | the recognition's path-safe name |
getBadge(Long id)
Returns: RecognitionBadge
Finds one of this topic's badges by its database id, which also confirms the badge belongs to this topic.
| Parameter | Description |
|---|---|
id | the badge id, must not be null |
getAllAwards()
Returns: List<RecognitionAward>
Every award ever made from this topic, across all its badges and levels. Despite the get prefix this reads from the database on the current session each time it is called, so it is expensive on a busy topic.
isOrgLevels()
Returns: boolean
Whether this topic makes awards at organisation level, ie the org level awards flag treated as false when it has never been set.
isLevelRegressionEnabled()
Returns: boolean
Whether participants can drop back down a level, ie the regression mode is one of the bi-directional values.
isLevelRegressionLosePoints()
Returns: boolean
Whether losing a level also deducts the points that were awarded for reaching it, ie the regression mode is bi-lose-points.
isApplicableForLevels(BaseEntity entity)
Returns: boolean
Whether the given profile or organisation is the kind of participant this topic awards levels to. An organisation-level topic only applies to organisations, and any other topic only applies to profiles.
| Parameter | Description |
|---|---|
entity | the profile or organisation being considered as a participant |
isAutoCalc()
Returns: boolean
Whether levels are calculated and awarded automatically by the nightly scan, ie the calc mode is auto.
isDryRun()
Returns: boolean
Whether levels are calculated but nothing is actually awarded, ie the calc mode is dry-run. Useful for checking a new topic's thresholds before it goes live.
isLevelPointsModeContinuous()
Returns: boolean
Whether level points are awarded progressively within a tier and reconciled on every check, ie the level points mode is continuous, rather than being awarded once when the level is reached.
findPeriods()
Returns: List<RecognitionPeriod>
Reads every recognition period defined for this topic from the database, using the current session. Only meaningful for a periodic topic; a continuous one has none.
isPeriodic()
Returns: boolean
Whether this topic is divided into recognition periods, ie the date mode is periodic.
findPeriodsForDate(Date now)
Returns: List<RecognitionPeriod>
Reads this topic's periods and returns those running at the given date, judged by the date range of each period's promotion. A period with no promotion is never returned, so it can never be current.
| Parameter | Description |
|---|---|
now | the date to test each period against |
findPeriod(Long periodId)
Returns: RecognitionPeriod
Reads this topic's periods and returns the one with the given id, which also confirms the period belongs to this topic.
| Parameter | Description |
|---|---|
periodId | the period id, must not be null |
rowId()
Returns: Long
The database identifier for this topic, as the generic row id used across Kademi entities. Same value as the id.
© 2025 Kademi Ltd