PointsManager

Need help? Ask Kademi

Manages loyalty points: creating points buckets, crediting and debiting balances, and calculating expiry and balance history. A points bucket is represented by a Reward and can be scoped to individual profiles or to organisations. Provides expiry calculation, balance and transaction history queries, and search across points credits and debits for reporting. Most methods are exported to server-side JavaScript and are reached from a request context via C(PointsManager.class).

Group: Managers

Properties

Property	Returns	Description
allocationRulePointsTag	PointsTag	The points tag configured on the rewards app to apply to points awarded via an allocation rule, for the current tenant organisation.
allocationRuleReasonCode	`String`	The reason code configured on the rewards app to apply to points awarded via an allocation rule, for the current tenant organisation.
allPointsExpiryRuleTypes	`List<PointsExpiryRuleType>`	All points expiry rule types available to the current tenant: rule types defined via account queries plus rule types contributed by active apps.
allPointsRuleTypes	`List<PointsRuleType>`	All points rule types available to the current tenant: the platform's built in static rule types, any rule types defined via account queries, and rule types contributed by active apps.
pointsBuckets	`List<Reward>`	All points buckets, as Rewards, defined for the current tenant organisation.
pointsTags	`List<PointsTag>`	All points tags defined for the current tenant admin organisation. Points tags are used to categorise points credits and debits.
reasonCodes	`Map<String,String>`	Configured points reason codes for this account, keyed by code with the description as the value, as defined by the rewards app.

Methods

calcEffectiveExpiryDate(Points p) · processExpiryForEntity(BaseEntity be, Reward r, Date from) · processExpiryForEntity(BaseEntity be, Reward r, Date from, Narrative narrative) · processExpiryForEntityDryRun(BaseEntity be, Reward r, Date from, Narrative narrative, List<Long> excludeIds, Boolean dryRun) · fullPointsHistory(BaseEntity be, Reward reward) · fullPointsHistoryEx(BaseEntity be, Reward reward) · fullPointsHistoryEx(BaseEntity be, Reward reward, boolean createExpiredLineItems) · findPointStatements(Reward reward, BaseEntity entity) · createPointsBucket(String newName, String newTitle, boolean indiv) · addGroupToPointsBucket(Reward pointsBucket, Group participantGroup) · pointsRuleParams(PointsAllocationSource pas) · pointsExpiryRuleParams(PointsAllocationSource pas) · pointsExpiryRuleParams(Reward reward) · pointsRuleType(String id) · getAllPointsRuleTypes() · pointsExpiryRuleType(String id) · getAllPointsExpiryRuleTypes() · findExpiring(Reward pointsBucket, BaseEntity recip, Date toDate) · calculateExpiry(Points points) · calculateExpiry(Points points, PointsAllocationSource pas) · findExpiringForAllEntities(Reward pointsBucket, Date toDate) · findExpiringForAllEntities(Reward pointsBucket, Date toDate, boolean clearSession) · calcFullPointsHistory(Reward pointsBucket, BaseEntity participant) · findPointsBucket(String name) · findPointsBucket(Long id) · getPointsBuckets() · availablePointsBuckets(Profile curUser) · availablePointsBuckets(Organisation org) · awardPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason) · awardPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason, PointsTag pointsTag) · debitPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason, String reasonCode) · newPointsRequest(BaseEntity participant, double points) · newPointsRequest() · processPointsRequest(PointsRequest pr) · getPointsTags() · findTag(String tagOrReasonCode) · createTag(String title, String code) · findPointsBalanceRecord(BaseEntity entity, Reward reward) · pointsBalance(Reward reward, BaseEntity baseEntity) · pointsType(String s) · balanceCalculationMode(String s) · pointsBalance(Reward reward, BaseEntity entity, boolean forceRecalc) · availableBalance(BaseEntity entity, Reward reward) · availableBalance(BaseEntity entity, Reward reward, Auction ignoreAuction) · updatePointsBalance(BaseEntity entity, Reward reward) · updatePointsBalance(BaseEntity entity, Reward reward, boolean invalidateOnly) · findParticipants(Reward reward, BaseEntity entity) · findParticipantForEntity(Reward reward, BaseEntity baseEntity) · findProfilesForEntity(Reward reward, BaseEntity baseEntity, int max) · transactions(BaseEntity recip, Reward reward) · transactions(BaseEntity recip, Reward reward, Date since, Date to) · transactions(BaseEntity recip, Reward reward, Date since, Date to, int limit) · sumAllPoints(BaseEntity baseEntity, String rewardName, Date from, Date to) · sumAllPoints(BaseEntity baseEntity, String rewardName, String pointsTag, Date from, Date to) · sumAllPoints(BaseEntity baseEntity, Reward reward, PointsTag pt, Date from, Date to) · sumAllDebits(BaseEntity baseEntity, String rewardName, String reasonCode, Date from, Date to) · sumAllPoints(ProfileBean profileBean, String rewardName, Date from, Date to) · sumAllPoints(ProfileBean profileBean, String rewardName, String pointsTag, Date from, Date to) · sumAllPoints(UserResource userResource, String rewardName, Date from, Date to) · sumAllPoints(UserResource userResource, String rewardName, String pointsTag, Date from, Date to) · sumAllPoints(OrgData orgData, String rewardName, Date from, Date to) · sumAllPoints(OrgData orgData, String rewardName, String pointsTag, Date from, Date to) · findPointsDebitLinks(RewardTransactionItem rti) · deletePointsDebitLink(PointsDebitLink debitLink) · getReasonCodes() · getAllocationRulePointsTag() · getAllocationRuleReasonCode() · findBySearch(String searchQ, Reward r, String reasonCode, String tagId, Date from, Date to, Long minPoints, Long maxPoints, SearchProperties searchProperties) · findBySearch(String searchQ, Reward r, String reasonCode, String tagId, Date from, Date to, Long minPoints, Long maxPoints, String recordType, SearchProperties searchProperties) · newPointsTransactionsSearch() · findBySearch(PointsTransactionsSearchBuilder b) · pointsStats(BaseEntity org, Reward reward, Date start, Date finish) · applicableMemberships(Profile p, Reward reward) · applicableOrgs(Profile p, Reward reward) · applicableMemberships(Organisation o, Reward reward, int max) · applicableProfiles(Organisation o, Reward reward, int max) · myPointsInfo(Reward reward, Integer max) · myPointsInfo(Reward reward, Integer max, Date since) · myPointsInfo(Reward reward, Integer max, Date since, OrgData org) · myPointsInfo(Reward reward, Integer max, Date since, Date to) · findApplicableMemberships(Profile p, Reward reward) · findParticipantsForReward(Profile p, Reward reward) · isSameParticipant(EntityBean entity, ProfileBean user) · lastCredit(BaseEntity participant, Reward bucket) · lastDebit(BaseEntity participant, Reward bucket) · deleteAndResetPoints(PointsAllocation pa) · findPointStatementFieldDefs(Reward pointsBucket)

`calcEffectiveExpiryDate(Points p)`

Returns: Date

Calculates the effective expiry date of a points record: the date and time the platform treats it as actually expired. When the owning reward uses an exact expiry mode this is the record's own expiry date; otherwise it is recalculated as the end of that day in the tenant's timezone.

Parameter	Description
`p`	the points record to calculate the effective expiry date for

`processExpiryForEntity(BaseEntity be, Reward r, Date from)`

Returns: ICalcContext

Processes points expiry for the given entity's points in the given reward from the given date, discarding the narrative of changes made. Equivalent to calling the four argument overload with a new, unused Narrative.

Parameter	Description
`be`	the participant, a profile or organisation, whose points are processed
`r`	the reward (points bucket) to process expiry for
`from`	the date to process expiry from

`processExpiryForEntity(BaseEntity be, Reward r, Date from, Narrative narrative)`

Returns: ICalcContext

Processes points expiry for the given entity's points in the given reward from the given date, recording a description of the changes made into the given narrative.

Parameter	Description
`be`	the participant, a profile or organisation, whose points are processed
`r`	the reward (points bucket) to process expiry for
`from`	the date to process expiry from
`narrative`	collects a human readable description of the processing that occurred

`processExpiryForEntityDryRun(BaseEntity be, Reward r, Date from, Narrative narrative, List<Long> excludeIds, Boolean dryRun)`

Returns: ICalcContext

Processes points expiry for the given entity's points in the given reward from the given date, optionally excluding specific points or debit records by id and optionally running as a dry run. When dryRun is true no database changes are persisted, but the narrative is still populated as if they had been.

Parameter	Description
`be`	the participant, a profile or organisation, whose points are processed
`r`	the reward (points bucket) to process expiry for
`from`	the date to process expiry from
`narrative`	collects a human readable description of the processing that occurred
`excludeIds`	ids of points and points debit records to exclude from the calculation, may be null
`dryRun`	when true, calculates the expiry outcome without persisting any changes

`fullPointsHistory(BaseEntity be, Reward reward)`

Returns: List<? extends IPointsLineItem>

Generates a complete list of line items detailing the full points history of the given base entity in the given reward, for all time. Each line item has the points balance at that point in time.

Parameter	Description
`be`	the participant, a Profile or Organisation, to build the history for
`reward`	the reward (points bucket) to build the history for

`fullPointsHistoryEx(BaseEntity be, Reward reward)`

Returns: ICalcContext

Generates a complete list of line items detailing the full points history of the given base entity in the given reward, for all time. Unlike fullPointsHistory this returns the full calculation context, which also carries artefacts of the calculation such as the list of active points records, not just the resulting line items.

Parameter	Description
`be`	the participant, a Profile or Organisation, to build the history for
`reward`	the reward (points bucket) to build the history for

`fullPointsHistoryEx(BaseEntity be, Reward reward, boolean createExpiredLineItems)`

Returns: ICalcContext

Generates a complete list of line items detailing the full points history of the given base entity in the given reward, for all time, optionally creating a line item for each expiry event. Returns null if either the entity or the reward is null.

Parameter	Description
`be`	the participant, a Profile or Organisation, to build the history for
`reward`	the reward (points bucket) to build the history for
`createExpiredLineItems`	when true, adds a line item for each points expiry event found

`findPointStatements(Reward reward, BaseEntity entity)`

Returns: List<PointStatement>

Finds the persisted point statements previously issued to the given entity for the given reward.

Parameter	Description
`reward`	the reward (points bucket) the statements belong to
`entity`	the participant, a Profile or Organisation, the statements were issued to

`createPointsBucket(String newName, String newTitle, boolean indiv)`

Returns: Reward

Creates and persists a new points bucket, as a Reward, for the current tenant organisation. The new bucket uses performance based balance calculation and is attributed to either profiles or organisations depending on indiv.

Parameter	Description
`newName`	the path safe, unique name for the new points bucket
`newTitle`	the display title for the new points bucket
`indiv`	when true the bucket is created for individual profile attribution, otherwise for organisation attribution

`addGroupToPointsBucket(Reward pointsBucket, Group participantGroup)`

Returns: void

Adds a group as a participant group on the given points bucket, so that members of the group become eligible participants in the reward.

Parameter	Description
`pointsBucket`	the reward (points bucket) to add the group to
`participantGroup`	the group to add as a participant of the points bucket

`pointsRuleParams(PointsAllocationSource pas)`

Returns: Map<String,String>

Parses the points rule configuration string on the given allocation source into a map of parameter name to value. Returns null if the allocation source has no rule type or no rule configuration.

Parameter	Description
`pas`	the points allocation source to read the points rule configuration from

`pointsExpiryRuleParams(PointsAllocationSource pas)`

Returns: Map<String,String>

Parses the points expiry rule configuration string on the given allocation source into a map of parameter name to value. Returns null if the allocation source has no expiry rule type or no expiry rule configuration.

Parameter	Description
`pas`	the points allocation source to read the points expiry rule configuration from

`pointsExpiryRuleParams(Reward reward)`

Returns: Map<String,String>

Parses the points expiry rule configuration string on the given reward into a map of parameter name to value. Returns null if the reward has no expiry rule type or no expiry rule configuration.

Parameter	Description
`reward`	the reward (points bucket) to read the points expiry rule configuration from

`pointsRuleType(String id)`

Returns: PointsRuleType

Finds a registered points rule type by its id, searching the built in static rule types, any account defined rule types, and rule types contributed by active apps. Returns null if id is blank or no rule type matches.

Parameter	Description
`id`	the id of the points rule type to find

`getAllPointsRuleTypes()`

Returns: List<PointsRuleType>

All points rule types available to the current tenant: the platform's built in static rule types, any rule types defined via account queries, and rule types contributed by active apps.

`pointsExpiryRuleType(String id)`

Returns: PointsExpiryRuleType

Finds a registered points expiry rule type by its id, searching account defined rule types and rule types contributed by active apps. Returns null if id is blank or no expiry rule type matches.

Parameter	Description
`id`	the id of the points expiry rule type to find

`getAllPointsExpiryRuleTypes()`

Returns: List<PointsExpiryRuleType>

All points expiry rule types available to the current tenant: rule types defined via account queries plus rule types contributed by active apps.

`findExpiring(Reward pointsBucket, BaseEntity recip, Date toDate)`

Returns: ExpiringPointsList

Calculates the recipient's current balance in the given points bucket and returns the points records within it that are due to expire before the given date, ie those with a remaining balance and an expiry date before toDate. Returns null if pointsBucket is null.

Parameter	Description
`pointsBucket`	the reward (points bucket) to check for expiring points
`recip`	the participant, a profile or organisation, to check expiring points for
`toDate`	points expiring before this date are included in the result

`calculateExpiry(Points points)`

Returns: Date

Calculates the expiry date that should apply to the given points record, using the reward's default expiry rule. Equivalent to calling the two argument overload with a null allocation source.

Parameter	Description
`points`	the points record to calculate the expiry date for

`calculateExpiry(Points points, PointsAllocationSource pas)`

Returns: Date

Calculates the expiry date that should apply to the given points record. If the allocation source, or the points' own reward, has a configured points expiry rule type, that rule is used to calculate the expiry date. Otherwise the expiry falls back to the reward's fixed valid-for-days and static expiry date, taking whichever of the two is earlier.

Parameter	Description
`points`	the points record to calculate the expiry date for
`pas`	the allocation source whose expiry rule should be preferred, may be null to use the reward's own rule

`findExpiringForAllEntities(Reward pointsBucket, Date toDate)`

Returns: Map<BaseEntity,ExpiringPointsList>

Finds the points due to expire before the given date, for every participant in the given points bucket. Equivalent to calling the three argument overload with clearSession false.

Parameter	Description
`pointsBucket`	the reward (points bucket) to check for expiring points
`toDate`	points expiring before this date are included in the result

`findExpiringForAllEntities(Reward pointsBucket, Date toDate, boolean clearSession)`

Returns: Map<BaseEntity,ExpiringPointsList>

Finds the points due to expire before the given date, for every participant in the given points bucket. Returns an empty map if pointsBucket is null. When clearSession is true, the Hibernate session is cleared and the points bucket refreshed before the per participant calculations run, to bound memory use over a large number of participants.

Parameter	Description
`pointsBucket`	the reward (points bucket) to check for expiring points
`toDate`	points expiring before this date are included in the result
`clearSession`	when true, clears the Hibernate session part way through the calculation

`calcFullPointsHistory(Reward pointsBucket, BaseEntity participant)`

Returns: List<? extends IPointsLineItem>

Dynamically generates the full points transaction history for the given participant in the given bucket. Unlike fullPointsHistory this ignores persisted points balance reconciliation records and applies expirations dynamically where an expiry debit is missing. Returns null if pointsBucket or participant is null.

Parameter	Description
`pointsBucket`	the reward (points bucket) to build the history for
`participant`	the participant, a profile or organisation, to build the history for

`findPointsBucket(String name)`

Returns: Reward

Finds a points bucket, as a Reward, by its name within the current tenant organisation.

Parameter	Description
`name`	the unique name of the points bucket to find

`findPointsBucket(Long id)`

Returns: Reward

Finds a points bucket, as a Reward, by its id within the current tenant organisation. Returns null if id is null or no bucket matches.

Parameter	Description
`id`	the id of the points bucket to find

`getPointsBuckets()`

Returns: List<Reward>

All points buckets, as Rewards, defined for the current tenant organisation.

`availablePointsBuckets(Profile curUser)`

Returns: List<Reward>

Finds the points buckets that the given profile is eligible to participate in, ie buckets whose participant group and organisation both apply to the profile.

Parameter	Description
`curUser`	the profile to find available points buckets for

`availablePointsBuckets(Organisation org)`

Returns: List<Reward>

Finds the points buckets whose participant scope includes the given organisation.

Parameter	Description
`org`	the organisation to find available points buckets for

`awardPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason)`

Returns: Points

Awards points to the given recipient in the given reward, with no points tag. Equivalent to calling the five argument overload with a null tag.

Parameter	Description
`recipient`	the participant, a profile or organisation, to award points to
`reward`	the reward (points bucket) to award points in
`numPoints`	the number of points to award
`reason`	a human readable description of why the points were awarded

`awardPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason, PointsTag pointsTag)`

Returns: Points

Awards points to the given recipient in the given reward, tagged with the given points tag. The recipient is resolved as a profile or an organisation depending on whether the reward is configured for individual or organisation attribution.

Parameter	Description
`recipient`	the participant, a profile or organisation, to award points to
`reward`	the reward (points bucket) to award points in
`numPoints`	the number of points to award
`reason`	a human readable description of why the points were awarded
`pointsTag`	the tag to categorise the awarded points with, may be null

`debitPoints(BaseEntity recipient, Reward reward, Double numPoints, String reason, String reasonCode)`

Returns: PointsDebit

Debits points from the given recipient's balance in the given reward, immediately, with the current date as the debit date.

Parameter	Description
`recipient`	the participant, a profile or organisation, to debit points from
`reward`	the reward (points bucket) to debit points in
`numPoints`	the number of points to debit
`reason`	a human readable description of why the points were debited
`reasonCode`	a code categorising the reason for the debit

`newPointsRequest(BaseEntity participant, double points)`

Returns: PointsRequest

Creates a new PointsRequest pre-populated with the given participant and points, to be further configured and then passed to processPointsRequest.

Parameter	Description
`participant`	the participant, a profile or organisation, the request is for
`points`	the number of points the request is for, positive to award, negative to debit

`newPointsRequest()`

Returns: PointsRequest

Creates a new, empty PointsRequest to be configured and then passed to processPointsRequest.

`processPointsRequest(PointsRequest pr)`

Returns: RewardTransactionItem

Processes a configured PointsRequest, creating either a points credit or a points debit depending on the sign of its points value. A positive value creates an award, using the request's team, tag, attachment and expiry date if set; a negative value creates a debit for the absolute value, and if a cart is set, links the debit to that cart's id. Returns null if the request's points value is zero.

Parameter	Description
`pr`	the configured points request to process

`getPointsTags()`

Returns: List<PointsTag>

All points tags defined for the current tenant admin organisation. Points tags are used to categorise points credits and debits.

`findTag(String tagOrReasonCode)`

Returns: PointsTag

Finds a points tag by its code within the current tenant admin organisation. Returns null if tagOrReasonCode is blank or no tag matches.

Parameter	Description
`tagOrReasonCode`	the code of the points tag to find

`createTag(String title, String code)`

Returns: PointsTag

Creates and persists a new points tag for the current tenant admin organisation.

Parameter	Description
`title`	the display title for the new points tag
`code`	the unique code for the new points tag

`findPointsBalanceRecord(BaseEntity entity, Reward reward)`

Returns: PointsBalance

Finds the persisted points balance record for the given entity in the given reward, if a balance has previously been calculated and cached for it.

Parameter	Description
`entity`	the participant, a profile or organisation, to find the balance record for
`reward`	the reward (points bucket) to find the balance record for

`pointsBalance(Reward reward, BaseEntity baseEntity)`

Returns: Double

Returns the current points balance for the given entity in the given reward, using the cached balance where available. Equivalent to calling the three argument overload with forceRecalc false.

Parameter	Description
`reward`	the reward (points bucket) to check the balance in
`baseEntity`	the participant, a profile or organisation, to check the balance for

`pointsType(String s)`

Returns: PointsType

Parses a points type name into the matching Reward.PointsType enum constant.

Parameter	Description
`s`	the name of the points type to parse

`balanceCalculationMode(String s)`

Returns: BalanceCalculationMode

Parses a balance calculation mode name into the matching Reward.BalanceCalculationMode enum constant.

Parameter	Description
`s`	the name of the balance calculation mode to parse

`pointsBalance(Reward reward, BaseEntity entity, boolean forceRecalc)`

Returns: Double

Returns the current points balance for the given entity in the given reward. When the reward is scoped to individual profiles and the entity is itself a profile, the profile is used directly as the participant, saving a membership lookup; otherwise the participant is resolved via the reward's participant groups.

Parameter	Description
`reward`	the reward (points bucket) to check the balance in
`entity`	the participant, a profile or organisation, to check the balance for
`forceRecalc`	when true, forces the balance to be recalculated rather than using a cached value

`availableBalance(BaseEntity entity, Reward reward)`

Returns: Double

Returns the entity's available points balance in the given reward, ie the balance minus any points reserved by open auction bids. Equivalent to calling the three argument overload with a null ignoreAuction.

Parameter	Description
`entity`	the participant, a profile or organisation, to check the available balance for
`reward`	the reward (points bucket) to check the available balance in

`availableBalance(BaseEntity entity, Reward reward, Auction ignoreAuction)`

Returns: Double

Returns the entity's available points balance in the given reward, ie the balance minus any points reserved by open auction bids, other than bids on the given auction which are ignored.

Parameter	Description
`entity`	the participant, a profile or organisation, to check the available balance for
`reward`	the reward (points bucket) to check the available balance in
`ignoreAuction`	an auction whose reserved bids should be excluded from the calculation, may be null

`updatePointsBalance(BaseEntity entity, Reward reward)`

Returns: Double

Recalculates and persists the cached points balance for the given entity in the given reward. Equivalent to calling the three argument overload with invalidateOnly false.

Parameter	Description
`entity`	the participant, a profile or organisation, to update the balance for
`reward`	the reward (points bucket) to update the balance in

`updatePointsBalance(BaseEntity entity, Reward reward, boolean invalidateOnly)`

Returns: Double

Recalculates and persists the cached points balance for the given entity in the given reward, or simply invalidates the cached balance without recalculating it when invalidateOnly is true.

Parameter	Description
`entity`	the participant, a profile or organisation, to update the balance for
`reward`	the reward (points bucket) to update the balance in
`invalidateOnly`	when true, only invalidates the cached balance rather than recalculating it

`findParticipants(Reward reward, BaseEntity entity)`

Returns: List<BaseEntity>

Finds the participants in the given reward associated with the given entity. When the entity is an organisation this can return multiple participants, such as its individually attributed member profiles.

Parameter	Description
`reward`	the reward (points bucket) to find participants in
`entity`	the profile or organisation to find participants for

`findParticipantForEntity(Reward reward, BaseEntity baseEntity)`

Returns: BaseEntity

Finds a single participant in the given reward for the given entity.

Parameter	Description
`reward`	the reward (points bucket) to find a participant in
`baseEntity`	the profile or organisation to find a participant for

`findProfilesForEntity(Reward reward, BaseEntity baseEntity, int max)`

Returns: List<Profile>

Finds the profiles who have control over points for the given reward and entity. When the entity is itself a profile this simply returns that profile. When the entity is an organisation, returns the profiles who hold points control of that organisation, up to the given maximum.

Parameter	Description
`reward`	the reward (points bucket) to find controlling profiles for
`baseEntity`	the profile or organisation to find controlling profiles for
`max`	the maximum number of profiles to return when baseEntity is an organisation

`transactions(BaseEntity recip, Reward reward)`

Returns: List<PointsTransaction>

Finds the points transactions for the given recipient in the given reward, over the common (default) reporting date range. Equivalent to calling the four argument overload with the common start and finish dates.

Parameter	Description
`recip`	the participant, a profile or organisation, to find transactions for
`reward`	the reward (points bucket) to find transactions in

`transactions(BaseEntity recip, Reward reward, Date since, Date to)`

Returns: List<PointsTransaction>

Finds the points transactions for the given recipient in the given reward, between the given dates. Equivalent to calling the five argument overload with a limit of 1000.

Parameter	Description
`recip`	the participant, a profile or organisation, to find transactions for
`reward`	the reward (points bucket) to find transactions in
`since`	only transactions on or after this date are included
`to`	only transactions on or before this date are included

`transactions(BaseEntity recip, Reward reward, Date since, Date to, int limit)`

Returns: List<PointsTransaction>

Finds the points transactions for the given recipient in the given reward, between the given dates, up to a maximum of limit results.

Parameter	Description
`recip`	the participant, a profile or organisation, to find transactions for
`reward`	the reward (points bucket) to find transactions in
`since`	only transactions on or after this date are included
`to`	only transactions on or before this date are included
`limit`	the maximum number of transactions to return, up to 1000

`sumAllPoints(BaseEntity baseEntity, String rewardName, Date from, Date to)`

Returns: Double

Sums all matching points credits, for all participants associated with the given entity, in the reward with the given name. Equivalent to calling the five argument overload with a null points tag.

Parameter	Description
`baseEntity`	the profile or organisation to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(BaseEntity baseEntity, String rewardName, String pointsTag, Date from, Date to)`

Returns: Double

Sums all matching points credits, for all participants associated with the given entity, in the reward with the given name, optionally restricted to a points tag.

Parameter	Description
`baseEntity`	the profile or organisation to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`pointsTag`	the code of the points tag to restrict the sum to, may be blank to include all tags
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(BaseEntity baseEntity, Reward reward, PointsTag pt, Date from, Date to)`

Returns: Double

Sums all matching points credits, for all participants associated with the given entity, in the given reward, optionally restricted to a points tag.

Parameter	Description
`baseEntity`	the profile or organisation to sum points for
`reward`	the reward (points bucket) to sum points in
`pt`	the points tag to restrict the sum to, may be null to include all tags
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllDebits(BaseEntity baseEntity, String rewardName, String reasonCode, Date from, Date to)`

Returns: Double

Sums all matching points debits, for all participants associated with the given entity, in the reward with the given name, optionally restricted to a reason code.

Parameter	Description
`baseEntity`	the profile or organisation to sum debits for
`rewardName`	the name of the reward (points bucket) to sum debits in
`reasonCode`	the reason code to restrict the sum to, may be blank to include all reasons
`from`	only debits issued on or after this date are included
`to`	only debits issued on or before this date are included

`sumAllPoints(ProfileBean profileBean, String rewardName, Date from, Date to)`

Returns: Double

Sums all matching points credits for the profile behind the given bean, in the reward with the given name. Equivalent to calling the five argument overload with a null points tag.

Parameter	Description
`profileBean`	the profile bean to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(ProfileBean profileBean, String rewardName, String pointsTag, Date from, Date to)`

Returns: Double

Sums all matching points credits for the profile behind the given bean, in the reward with the given name, optionally restricted to a points tag.

Parameter	Description
`profileBean`	the profile bean to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`pointsTag`	the code of the points tag to restrict the sum to, may be blank to include all tags
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(UserResource userResource, String rewardName, Date from, Date to)`

Returns: Double

Sums all matching points credits for the profile behind the given user resource, in the reward with the given name. Equivalent to calling the five argument overload with a null points tag.

Parameter	Description
`userResource`	the user resource to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(UserResource userResource, String rewardName, String pointsTag, Date from, Date to)`

Returns: Double

Sums all matching points credits for the profile behind the given user resource, in the reward with the given name, optionally restricted to a points tag.

Parameter	Description
`userResource`	the user resource to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`pointsTag`	the code of the points tag to restrict the sum to, may be blank to include all tags
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(OrgData orgData, String rewardName, Date from, Date to)`

Returns: Double

Sums all matching points credits for the organisation behind the given org data, in the reward with the given name. Equivalent to calling the five argument overload with a null points tag.

Parameter	Description
`orgData`	the org data to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`sumAllPoints(OrgData orgData, String rewardName, String pointsTag, Date from, Date to)`

Returns: Double

Sums all matching points credits for the organisation behind the given org data, in the reward with the given name, optionally restricted to a points tag.

Parameter	Description
`orgData`	the org data to sum points for
`rewardName`	the name of the reward (points bucket) to sum points in
`pointsTag`	the code of the points tag to restrict the sum to, may be blank to include all tags
`from`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`findPointsDebitLinks(RewardTransactionItem rti)`

Returns: List<PointsDebitLink>

Finds the points debit links associated with the given transaction item, ie the debits that reconcile against a points credit, or the credits reconciled by a points debit. Returns null if rti is null.

Parameter	Description
`rti`	the transaction item, a Points credit or a PointsDebit, to find debit links for

`deletePointsDebitLink(PointsDebitLink debitLink)`

Returns: void

Deletes the given points debit link, removing the reconciliation it recorded between a points credit and a points debit.

Parameter	Description
`debitLink`	the points debit link to delete

`getReasonCodes()`

Returns: Map<String,String>

Configured points reason codes for this account, keyed by code with the description as the value, as defined by the rewards app.

`getAllocationRulePointsTag()`

Returns: PointsTag

The points tag configured on the rewards app to apply to points awarded via an allocation rule, for the current tenant organisation.

`getAllocationRuleReasonCode()`

Returns: String

The reason code configured on the rewards app to apply to points awarded via an allocation rule, for the current tenant organisation.

`findBySearch(String searchQ, Reward r, String reasonCode, String tagId, Date from, Date to, Long minPoints, Long maxPoints, SearchProperties searchProperties)`

Returns: ListAndCount

Searches points credits and debits for the current tenant, matching the given filters. Equivalent to calling the nine argument overload with a null recordType, ie including both credits and debits.

Parameter	Description
`searchQ`	free text search against the participant's name, org id or the transaction's reason, may be blank
`r`	restricts results to this reward (points bucket), may be null to search all rewards
`reasonCode`	restricts debit results to this reason code, may be blank; use "NONE" to match records with no reason code
`tagId`	restricts credit results to this points tag id, may be blank; use "NONE" to match records with no tag
`from`	only transactions issued on or after this date are included, may be null
`to`	only transactions issued on or before this date are included, may be null
`minPoints`	restricts results to transactions with at least this many points, may be null
`maxPoints`	restricts results to transactions with at most this many points, may be null
`searchProperties`	paging and sort order to apply to the results, may be null

`findBySearch(String searchQ, Reward r, String reasonCode, String tagId, Date from, Date to, Long minPoints, Long maxPoints, String recordType, SearchProperties searchProperties)`

Returns: ListAndCount

Searches points credits and debits for the current tenant, matching the given filters. Builds a PointsTransactionsSearchBuilder from the arguments and delegates to findBySearch(PointsTransactionsSearchBuilder).

Parameter	Description
`searchQ`	free text search against the participant's name, org id or the transaction's reason, may be blank
`r`	restricts results to this reward (points bucket), may be null to search all rewards
`reasonCode`	restricts debit results to this reason code, may be blank; use "NONE" to match records with no reason code
`tagId`	restricts credit results to this points tag id, may be blank; use "NONE" to match records with no tag
`from`	only transactions issued on or after this date are included, may be null
`to`	only transactions issued on or before this date are included, may be null
`minPoints`	restricts results to transactions with at least this many points, may be null
`maxPoints`	restricts results to transactions with at most this many points, may be null
`recordType`	restricts results to "C" for credits only or "D" for debits only, may be blank to include both
`searchProperties`	paging and sort order to apply to the results, may be null

`newPointsTransactionsSearch()`

Returns: PointsTransactionsSearchBuilder

Creates a new PointsTransactionsSearchBuilder for searching points transactions (credits and debits). Set its properties, using simple assignment or fluent chaining, then call its search() method to get results as a ListAndCount.

`findBySearch(PointsTransactionsSearchBuilder b)`

Returns: ListAndCount

Searches points credits and debits for the current tenant using the filters set on the given search builder, built with newPointsTransactionsSearch. Runs as a single UNION query over the points and points_debit tables with a matching count query for pagination.

Parameter	Description
`b`	the configured search builder describing the filters and paging to apply

`pointsStats(BaseEntity org, Reward reward, Date start, Date finish)`

Returns: PointsStats

Builds a summary of points credit and debit counts for the given entity, reward and date range.

Parameter	Description
`org`	the participant, a profile or organisation, to build stats for
`reward`	the reward (points bucket) to build stats for
`start`	only transactions on or after this date are included
`finish`	only transactions on or before this date are included

`applicableMemberships(Profile p, Reward reward)`

Returns: List<GroupMembership>

Finds the profile's group memberships that are applicable to the given reward, ie memberships of groups defined as participants on the reward. Returns null if the reward has no participant groups.

Parameter	Description
`p`	the profile to find applicable memberships for
`reward`	the reward (points bucket) to check participant groups against

`applicableOrgs(Profile p, Reward reward)`

Returns: List<Organisation>

Finds the distinct organisations, other than the reward's own organisation, that the profile belongs to via a group membership applicable to the given reward. Returns null if the profile has no applicable memberships.

Parameter	Description
`p`	the profile to find applicable organisations for
`reward`	the reward (points bucket) to check participant groups against

`applicableMemberships(Organisation o, Reward reward, int max)`

Returns: List<GroupMembership>

Finds group memberships within the given organisation that are applicable to the given reward, ie memberships of groups defined as participants on the reward, up to a maximum count. Returns null if the reward has no participant groups.

Parameter	Description
`o`	the organisation to find applicable memberships within
`reward`	the reward (points bucket) to check participant groups against
`max`	the maximum number of memberships to return

`applicableProfiles(Organisation o, Reward reward, int max)`

Returns: List<Profile>

Finds the distinct profiles within the given organisation that hold a group membership applicable to the given reward, up to a maximum count. Returns an empty list if o or reward is null.

Parameter	Description
`o`	the organisation to find applicable profiles within
`reward`	the reward (points bucket) to check participant groups against
`max`	the maximum number of profiles to return

`myPointsInfo(Reward reward, Integer max)`

Returns: MyRewardInfo

Builds a leaderboard summary of points earned by the current user's team in the given reward, for all time.

Parameter	Description
`reward`	the reward (points bucket) to build the leaderboard for
`max`	the maximum number of team members to include in the leaderboard

`myPointsInfo(Reward reward, Integer max, Date since)`

Returns: MyRewardInfo

Builds a leaderboard summary of points earned by the current user's team in the given reward, since the given date.

Parameter	Description
`reward`	the reward (points bucket) to build the leaderboard for
`max`	the maximum number of team members to include in the leaderboard
`since`	only points issued on or after this date are included

`myPointsInfo(Reward reward, Integer max, Date since, OrgData org)`

Returns: MyRewardInfo

Builds a leaderboard summary of points earned by the given organisation's team in the given reward, since the given date.

Parameter	Description
`reward`	the reward (points bucket) to build the leaderboard for
`max`	the maximum number of team members to include in the leaderboard
`since`	only points issued on or after this date are included
`org`	the organisation whose team the leaderboard is built for

`myPointsInfo(Reward reward, Integer max, Date since, Date to)`

Returns: MyRewardInfo

Builds a leaderboard summary of points earned by the current user's team in the given reward, between the given dates.

Parameter	Description
`reward`	the reward (points bucket) to build the leaderboard for
`max`	the maximum number of team members to include in the leaderboard
`since`	only points issued on or after this date are included
`to`	only points issued on or before this date are included

`findApplicableMemberships(Profile p, Reward reward)`

Returns: List<GroupMembership>

Finds the profile's group memberships that are applicable to the given reward, delegating to RewardService.

Parameter	Description
`p`	the profile to find applicable memberships for
`reward`	the reward (points bucket) to check participant groups against

`findParticipantsForReward(Profile p, Reward reward)`

Returns: List<BaseEntity>

Finds the participants in the given reward associated with the given profile, delegating to RewardService.

Parameter	Description
`p`	the profile to find participants for
`reward`	the reward (points bucket) to find participants in

`isSameParticipant(EntityBean entity, ProfileBean user)`

Returns: boolean

Returns true if the given user represents the same participant as the given entity, for the purpose of rewards. When entity is an organisation, checks whether the user's profile belongs to it; when entity is a profile, compares their entity names directly.

Parameter	Description
`entity`	the participant entity, a profile or organisation, to compare against
`user`	the user to check

`lastCredit(BaseEntity participant, Reward bucket)`

Returns: Points

Finds the most recently issued points credit for the given participant in the given bucket.

Parameter	Description
`participant`	the participant, a profile or organisation, to find the last credit for
`bucket`	the reward (points bucket) to find the last credit in

`lastDebit(BaseEntity participant, Reward bucket)`

Returns: PointsDebit

Finds the most recently issued points debit for the given participant in the given bucket.

Parameter	Description
`participant`	the participant, a profile or organisation, to find the last debit for
`bucket`	the reward (points bucket) to find the last debit in

`deleteAndResetPoints(PointsAllocation pa)`

Returns: void

Deletes the given points allocation and resets any points and balance records it produced, delegating to RewardService.

Parameter	Description
`pa`	the points allocation to delete and reset

`findPointStatementFieldDefs(Reward pointsBucket)`

Returns: List<PointStatementFieldDef>

Finds all point statement field definitions configured in XML for the given points bucket.

Parameter	Description
`pointsBucket`	the reward (points bucket) to find field definitions for

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