Manages promotions and points buckets, both modelled by the Reward entity, plus reward categories and reward entries awarded to participants. Provides find, create and update operations for promotions and points buckets, builders for constructing a promotion (PromotionBuilder), a reward category (RewardCategoryBuilder) and a reward entry (RewardEntryBuilder), and participant search helpers used to work out who is eligible for a given promotion. Registered as the Spring bean "promotions.manager" and normally reached via the request-scoped lookup RequestContext.C(PromotionsManager .class); several of the builder methods are also exported to GraalJS scripts via HostAccess.Export.

Group: Managers

---

Properties

---

Methods

duplicatePromotion(String name, Reward sourcePromo) · createPromotion(String promoId, String promoTitle, Website website, String promoType) · updatePromotion(Reward promotion) · updatePromotionContent(Reward promotion, String bodyContent, String termsContent) · updatePromotionProperties(Reward promotion, Map<String,String> propValues) · newPromotionBuilder(String id, String title, Website website, String promoType) · getPointsAllocationSources() · findPointsAllocationSource(String name) · getPromotionMechanicTypes() · findPromotionMechanicType(String name) · findRewardEntry(Long id) · findRewardEntries(Profile user, Reward promo) · deleteRewardEntry(RewardEntry re) · getAllRewards() · getAllPromotions() · findPromotions(String query, String sortField, String sortDir) · deletePromo(Reward reward) · findPromotionsAfter(Date dt) · matchesParticipantSelector(Reward promo, BaseEntity entity) · matchesParticipantSelector(List<KSelectorItem> sels, Organisation entity) · findPointsBucket(long id) · findPointsBucket(String name) · findPromotion(String name) · findPromotionById(long id) · getPointsBuckets() · promotions(Boolean open, Date now) · availablePromotions() · availablePromotions(Date now, Profile curUser) · availablePromotions(Date now, Profile curUser, Boolean open) · activePromotions() · isMatchingPromoCode(String code, Reward promotion) · isElligbleUser(Profile user, Reward promotion) · isElligbleParticipant(BaseEntity participant, Reward promotion) · isActive(Reward promotion) · isStarted(Reward promotion) · promotionDetails(Reward reward) · numEntries(Reward promo) · findAnswerKeys(Reward reward) · newRewardEntryBuilder(Reward reward, Profile enteredProfile) · submitEntry(RewardEntryBuilder b) · participantSelectors(Reward promo) · newParticipantSearch() · countParticipants(ParticipantSearchBuilder psb) · findParticipants(Reward promo) · findParticipants(Reward promo, Boolean orgs) · findParticipants(ParticipantSearchBuilder psb) · useParticipants(ParticipantSearchBuilder psb, Consumer<BaseEntity> callback) · findRewardEntriesForUser(Reward reward, Profile user) · findUserAttachmentHash(Reward reward, Profile user) · findRewardEntriesWithAttachment(Reward reward) · findPromotionTerm(Reward reward) · putPromotionImage(Reward reward, String hash, String name) · updatePromotionImage(Reward reward, String newHash) · addPromotionGroup(Reward reward, Group group) · removePromotionGroup(Reward reward, Group group) · countPromotionEntries(Reward reward) · findPromotionsByType(String promotionType) · rewardEntryStatus(String s) · updateWinningEntry(RewardEntry entry) · newRewardCategoryBuilder(String name, String title) · getRewardCategories() · findRewardCategoryByName(String name) · updateRewardCategory(RewardCategory category) · deleteRewardCategory(RewardCategory category)

duplicatePromotion(String name, Reward sourcePromo)

Returns: Reward

Creates a new Reward by copying the core fields (dates, points org types, image, title, url, status, website and group filters) from an existing promotion, then copies the source promotion's content directory (if any) across to the new promotion's rewards folder. Throws a RuntimeException if there is no current user or if saving the copied content fails.

createPromotion(String promoId, String promoTitle, Website website, String promoType)

Returns: Reward

Creates and persists a new promotion using the default builder settings, then records a "create-promotion" telemetry event for the account.

updatePromotion(Reward promotion)

Returns: void

Saves changes to an existing promotion or points bucket entity.

updatePromotionContent(Reward promotion, String bodyContent, String termsContent)

Returns: void

Updates the promotion's body and terms content, stored as files in the promotion's directory in the rewards branch. The body is saved into the "details" property for historical reasons, and the terms are written to a terms.html file; either can be omitted by passing null to leave it unchanged.

updatePromotionProperties(Reward promotion, Map<String,String> propValues)

Returns: void

Merges the given values into the promotion's stored properties file, in its directory in the rewards branch. Blank values are ignored, so existing properties are only overwritten when a non-blank replacement is supplied.

newPromotionBuilder(String id, String title, Website website, String promoType)

Returns: PromotionBuilder

Creates a builder for constructing and persisting a new promotion.

getPointsAllocationSources()

Returns: List<PointsAllocationSource>

Looks up all points allocation sources configured for the current tenant organisation.

findPointsAllocationSource(String name)

Returns: PointsAllocationSource

Looks up a points allocation source by name within the current tenant organisation.

getPromotionMechanicTypes()

Returns: List<PromotionMechanicType>

Lists the promotion mechanic types registered with the ApplicationManager, for example the types of rewards apps installed on the account.

findPromotionMechanicType(String name)

Returns: PromotionMechanicType

Looks up a registered promotion mechanic type by its name.

findRewardEntry(Long id)

Returns: RewardEntry

Looks up a reward entry by its id within the current tenant organisation.

findRewardEntries(Profile user, Reward promo)

Returns: List<RewardEntry>

Finds the reward entries a user has for a given promotion.

deleteRewardEntry(RewardEntry re)

Returns: void

Deletes a reward entry. Does nothing if the given entry is null. Callers are responsible for ensuring no ModuleStatus, Referral or ReferralAcceptance still references the entry, as those relations prevent deletion.

getAllRewards()

Returns: List<Reward>

Lists every promotion and points bucket belonging to the current tenant organisation.

getAllPromotions()

Returns: PromotionsList

Lists every promotion (excluding points buckets) belonging to the current tenant organisation.

findPromotions(String query, String sortField, String sortDir)

Returns: PromotionsList

Searches the current tenant organisation's promotions by a free-text query, with the results sorted.

deletePromo(Reward reward)

Returns: void

Soft-deletes a promotion or points bucket, recording the current user and time as the deleting user and date.

findPromotionsAfter(Date dt)

Returns: PromotionsList

Finds all promotions in the current tenant organisation with a start date after the given date.

matchesParticipantSelector(Reward promo, BaseEntity entity)

Returns: boolean

Checks whether an entity (a profile or organisation) matches a promotion's participant selectors.

matchesParticipantSelector(List<KSelectorItem> sels, Organisation entity)

Returns: boolean

Checks whether an organisation matches the given list of participant selectors.

findPointsBucket(long id)

Returns: Reward

Looks up a points bucket by id within the current tenant organisation.

findPointsBucket(String name)

Returns: Reward

Looks up a points bucket by name within the current tenant organisation.

findPromotion(String name)

Returns: Reward

Looks up a promotion or points bucket by name within the current tenant organisation.

findPromotionById(long id)

Returns: Reward

Looks up a promotion or points bucket by id within the current tenant organisation.

getPointsBuckets()

Returns: List<Reward>

Lists all points buckets belonging to the current tenant organisation.

promotions(Boolean open, Date now)

Returns: PromotionsList

Finds promotions for the current tenant organisation, filtered by whether they have finished as at the given date. Passing null for open returns every promotion regardless of status.

availablePromotions()

Returns: PromotionsList

Finds the open promotions currently available to the current user, evaluated as at now.

availablePromotions(Date now, Profile curUser)

Returns: PromotionsList

Finds the open promotions available to a given user as at a given date.

availablePromotions(Date now, Profile curUser, Boolean open)

Returns: PromotionsList

Finds the promotions available to a given user as at a given date, optionally filtered to only open ones.

activePromotions()

Returns: PromotionsList

Finds the promotions that are currently open, as at now.

isMatchingPromoCode(String code, Reward promotion)

Returns: boolean

Checks whether the given code matches one of the promotion's configured entry codes.

isElligbleUser(Profile user, Reward promotion)

Returns: boolean

Checks whether a user is eligible for a promotion, based on the promotion's participant selectors. Returns false if the promotion is null.

isElligbleParticipant(BaseEntity participant, Reward promotion)

Returns: boolean

Checks whether a participant, either a profile or an organisation, is eligible for a promotion, based on the promotion's participant selectors and, for profiles, org criteria.

isActive(Reward promotion)

Returns: boolean

Checks whether a promotion is currently active, meaning it has started (or has no start date), has not finished (or has no end date), and is not null.

isStarted(Reward promotion)

Returns: boolean

Checks whether a promotion is viewable, meaning it has passed its start date. Unlike isActive, this remains true after the finish date. Equivalent to calling promotion.isViewable(now). Returns false if the promotion is null.

promotionDetails(Reward reward)

Returns: PromotionBean

Loads the promotion's stored content properties (as saved by updatePromotionContent and updatePromotionProperties) into a PromotionBean. Returns null if the reward is null.

numEntries(Reward promo)

Returns: long

Counts the reward entries recorded against a promotion. Returns 0 if the promotion is null.

findAnswerKeys(Reward reward)

Returns: List<String>

Finds the distinct quiz answer keys that have been submitted for a promotion, sorted in natural order.

newRewardEntryBuilder(Reward reward, Profile enteredProfile)

Returns: RewardEntryBuilder

Creates a builder for constructing and submitting a new reward entry, recording that a profile has entered or been awarded a promotion.

submitEntry(RewardEntryBuilder b)

Returns: RewardEntry

Builds and persists a RewardEntry from a configured RewardEntryBuilder. If quiz answers were added to the builder, also creates the RewardQuizSubmission, QuizAttempt and QuizAnswer records, uploading any answered files via the FileStorageManager. The entry's approval status defaults to pending or accepted depending on whether the reward requires approval, unless an explicit status was set on the builder. Fires a reward entry status updated event once the entry is saved.

participantSelectors(Reward promo)

Returns: List<KSelectorItem>

Parses and returns the participant selectors configured on a promotion.

newParticipantSearch()

Returns: ParticipantSearchBuilder

Creates a builder for searching for the profiles or organisations eligible to participate in a promotion.

countParticipants(ParticipantSearchBuilder psb)

Returns: int

Counts the profiles or organisations matching a participant search, without loading the full result set.

findParticipants(Reward promo)

Returns: Collection<BaseEntity>

Finds the profiles eligible to participate in a promotion, based on its group and organisation type filters.

findParticipants(Reward promo, Boolean orgs)

Returns: Collection<BaseEntity>

Finds the profiles or organisations eligible to participate in a promotion, based on its group and organisation type filters.

findParticipants(ParticipantSearchBuilder psb)

Returns: Collection<BaseEntity>

Finds the profiles or organisations matching a configured participant search, including any paging limits set on the builder.

useParticipants(ParticipantSearchBuilder psb, Consumer<BaseEntity> callback)

Returns: void

Streams the profiles or organisations matching a configured participant search to a callback, rather than loading them all into memory at once. Does nothing if the search has no criteria.

findRewardEntriesForUser(Reward reward, Profile user)

Returns: List<RewardEntry>

Finds the reward entries a user has for a given promotion.

findUserAttachmentHash(Reward reward, Profile user)

Returns: String

Finds the attachment hash from the first of the user's reward entries for this promotion that has an attachment. The hash can be used with /_hashes/files/{hash} to display the file. Returns null if the promotion or user is null, or no matching entry has an attachment.

findRewardEntriesWithAttachment(Reward reward)

Returns: List<RewardEntry>

Finds the reward entries for a promotion that have a non-blank attachment hash.

findPromotionTerm(Reward reward)

Returns: String

Reads the terms and conditions content stored for a promotion. Returns null if the terms cannot be loaded, for example if none have been saved yet.

putPromotionImage(Reward reward, String hash, String name)

Returns: ItemImage

Sets the promotion's image from an already-uploaded file.

updatePromotionImage(Reward reward, String newHash)

Returns: ItemImage

Replaces the promotion's existing image with a new version, for example after the image has been cropped.

addPromotionGroup(Reward reward, Group group)

Returns: void

Adds a group to a promotion's group filter.

removePromotionGroup(Reward reward, Group group)

Returns: void

Removes a group from a promotion's group filter.

countPromotionEntries(Reward reward)

Returns: long

Counts the reward entries recorded against a promotion.

findPromotionsByType(String promotionType)

Returns: List<Reward>

Finds the promotions in the current tenant organisation with the given promotion mechanic type.

rewardEntryStatus(String s)

Returns: RewardEntryStatus

Parses a reward entry status name into its RewardEntryStatus enum value.

updateWinningEntry(RewardEntry entry)

Returns: void

Marks a reward entry as the winner, setting its approval status to WINNER and saving it.

newRewardCategoryBuilder(String name, String title)

Returns: RewardCategoryBuilder

Creates a builder for constructing and persisting a new reward category.

getRewardCategories()

Returns: List<RewardCategory>

Lists all reward categories belonging to the current tenant organisation.

findRewardCategoryByName(String name)

Returns: RewardCategory

Looks up a reward category by name within the current tenant organisation.

updateRewardCategory(RewardCategory category)

Returns: void

Saves changes to an existing reward category.

deleteRewardCategory(RewardCategory category)

Returns: void

Deletes a reward category.