To get full access to the Kademi Hub existing customers can login here, or new customers can register here.
Owns the voucher domain: creating voucher types and vouchers, allocating vouchers to profiles, redeeming them and tracking their status history. Reached from server-side JS as the registered service "voucherManager". Most operations run against a single voucher (found by ID or keyword) or against a voucher type, and are exposed either directly or through the fluent VoucherTypeAllocationBuilder, VoucherAllocationBuilder, VoucherTypeBuilder and VoucherStatusBuilder inner classes for building up allocation, creation and status-change requests.
Group: Managers
Properties
| Property | Returns | Description |
|---|---|---|
| allVoucherExpiryRuleTypes | List<VoucherExpiryRuleType> | All available voucher expiration date calculators: the account-specific JsVoucherExpiryRuleType instances configured in that account's Queries repo (mirroring PointsManager.getAllPointsExpiryRuleTypes()). No app-registered-builder tier - unlike points expiry rules, this is intended to be custom per-account configuration. |
| allVoucherTypes | List<VoucherType> | All voucher types belonging to the current tenant organisation. |
| voucherStatusCodes | Map<String,String> | Returns all defined voucher status codes and their human-readable descriptions. |
Methods
getAllVoucherExpiryRuleTypes() · voucherExpiryRuleType(String id) · voucherExpiryRuleParams(VoucherType voucherType) · allocate(VoucherType vt, int num, String allocatedTo, Profile curUser, Date now, Organisation org, String notes) · allocate(VoucherType vt, int num, Profile allocatedTo, Profile curUser, Date now, Organisation org, String notes) · customFieldNames(VoucherType voucherType) · getAllVoucherTypes() · findVoucherType(String name) · findVoucher(String voucherId, VoucherType allowedType) · findVouchersForUser(Profile profile, int maxResult, boolean noBlankStatus, Website website) · findVouchersByIds(List<Long> voucherIds, VoucherType voucherType) · findVouchersByKeywords(String voucherQuery, VoucherType voucherType, boolean noBlankStatus, Profile profile, Website website) · findRedeemerOrgs(Profile curUser, Website website) · canRedeem(Voucher voucher) · redeem(Voucher voucher, Profile redeemer, String notes, Organisation redeemerOrg) · fireVoucherChangeEvent(Voucher voucher, String oldStatus) · findVoucherById(Long id) · toVoucherBean(Voucher voucher) · createVouchers(VoucherType voucherType, Long numVouchers) · allocate(VoucherAllocationBuilder b) · findAvailableVoucher(VoucherType vt) · findAvailableVoucher(VoucherType vt, List<Long> excludedVoucherIds) · allocate(Voucher voucher, Profile profile, String allocatedToId, String notes, Organisation redeemerOrg) · generateIdFromTemplate(String voucherIdTemplate) · randomHex(int numDigits) · randomInt(int numDigits) · statusText(String status) · newVoucherAllocationBuilder(VoucherType type) · saveVoucherExtraFieldValues(Voucher voucher, Map<String,String> extraFieldValues) · findVoucherExtraFieldValues(Voucher voucher) · findVoucherTypeExtraFields(VoucherType voucherType) · deleteVoucher(Voucher voucher, Profile profile) · newVoucherTypeBuilder() · newVoucherTypeBuilder(VoucherType voucherType) · getVoucherStatusCodes() · newVoucherStatusBuilder(Voucher voucher)
getAllVoucherExpiryRuleTypes()
Returns: List<VoucherExpiryRuleType>
All available voucher expiration date calculators: the account-specific JsVoucherExpiryRuleType instances configured in that account's Queries repo (mirroring PointsManager.getAllPointsExpiryRuleTypes()). No app-registered-builder tier - unlike points expiry rules, this is intended to be custom per-account configuration.
voucherExpiryRuleType(String id)
Returns: VoucherExpiryRuleType
Looks up one of this account's voucher expiry rule types by ID.
| Parameter | Description |
|---|---|
id | the voucher expiry rule type id to look up |
voucherExpiryRuleParams(VoucherType voucherType)
Returns: Map<String,String>
Parses the voucher type's configured expiration calculator parameters string into a map, for passing to its expiry rule type's calculator.
| Parameter | Description |
|---|---|
voucherType | the voucher type to read the expiration calculator config from |
allocate(VoucherType vt, int num, String allocatedTo, Profile curUser, Date now, Organisation org, String notes)
Returns: List<Voucher>
Allocates vouchers of the given type without setting the voucher's allocatedTo profile. This method assigns the given identifier to only the allocatedToId property of each allocated voucher.
| Parameter | Description |
|---|---|
vt | the voucher type to allocate from |
num | the number of vouchers to allocate |
allocatedTo | the identifier of the recipient, stored as allocatedToId |
curUser | the profile performing the allocation |
now | the date the allocation is happening |
org | the organisation the vouchers are allocated for redemption at |
notes | notes to record against each allocation |
allocate(VoucherType vt, int num, Profile allocatedTo, Profile curUser, Date now, Organisation org, String notes)
Returns: List<Voucher>
Allocates vouchers of the given type to a known profile. This method assigns the value to both the allocatedToId and allocatedTo properties of each allocated voucher.
| Parameter | Description |
|---|---|
vt | the voucher type to allocate from |
num | the number of vouchers to allocate |
allocatedTo | the profile to allocate the vouchers to |
curUser | the profile performing the allocation |
now | the date the allocation is happening |
org | the organisation the vouchers are allocated for redemption at |
notes | notes to record against each allocation |
customFieldNames(VoucherType voucherType)
Returns: List<String>
Returns an ordered list of the names of the custom fields configured on the given voucher type's fieldset.
| Parameter | Description |
|---|---|
voucherType | the voucher type to read custom field names from |
getAllVoucherTypes()
Returns: List<VoucherType>
All voucher types belonging to the current tenant organisation.
findVoucherType(String name)
Returns: VoucherType
Looks up a voucher type belonging to the current tenant organisation by its name.
| Parameter | Description |
|---|---|
name | the voucher type's name |
findVoucher(String voucherId, VoucherType allowedType)
Returns: Voucher
Looks up a voucher by its user-facing ID, restricted to a specific voucher type.
| Parameter | Description |
|---|---|
voucherId | the voucher's user-facing ID |
allowedType | the voucher type the voucher must belong to |
findVouchersForUser(Profile profile, int maxResult, boolean noBlankStatus, Website website)
Returns: List<Voucher>
Returns the vouchers available to a profile, based on the redeemer organisations it belongs to for the given website.
| Parameter | Description |
|---|---|
profile | the profile to find vouchers for |
maxResult | the maximum number of vouchers to return |
noBlankStatus | if true, exclude all vouchers with null or empty status |
website | the website whose redeemer role memberships determine the profile's organisations |
findVouchersByIds(List<Long> voucherIds, VoucherType voucherType)
Returns: List<Voucher>
Returns the vouchers of the given type matching a list of voucher IDs.
| Parameter | Description |
|---|---|
voucherIds | the internal IDs of the vouchers to find |
voucherType | the voucher type the vouchers must belong to |
findVouchersByKeywords(String voucherQuery, VoucherType voucherType, boolean noBlankStatus, Profile profile, Website website)
Returns: List<Voucher>
Searches for vouchers of a given type matching a keyword query, restricted to the organisations the profile can redeem vouchers at on the given website.
| Parameter | Description |
|---|---|
voucherQuery | the search keywords |
voucherType | the voucher type to search within |
noBlankStatus | if true, exclude all vouchers with null or empty status |
profile | the profile whose redeemer organisations scope the search |
website | the website whose redeemer role memberships determine the profile's organisations |
findRedeemerOrgs(Profile curUser, Website website)
Returns: List<Organisation>
Finds the organisations at which the given profile holds the voucher redeemer role for the given website, resolving each membership to its effective within-organisation.
| Parameter | Description |
|---|---|
curUser | the profile to look up redeemer memberships for, or null |
website | the website the redeemer role is checked against |
canRedeem(Voucher voucher)
Returns: boolean
Checks whether a voucher is currently available for redemption, i.e. not already redeemed, expired or deleted.
| Parameter | Description |
|---|---|
voucher | the voucher to check |
redeem(Voucher voucher, Profile redeemer, String notes, Organisation redeemerOrg)
Returns: boolean
Redeems a voucher: asks registered apps whether the redemption should be allowed, then changes the voucher's status to redeemed and fires the voucher change event. Throws if any app objects to the redemption.
| Parameter | Description |
|---|---|
voucher | the voucher to redeem |
redeemer | the profile redeeming the voucher |
notes | notes to record against the redemption |
redeemerOrg | the organisation the voucher is being redeemed at |
fireVoucherChangeEvent(Voucher voucher, String oldStatus)
Returns: void
Fires the voucher-updated index event and, if the voucher's status actually changed, a voucher funnel event (issued or state-changed as appropriate). Called after any operation that changes a voucher's status.
| Parameter | Description |
|---|---|
voucher | the voucher whose status may have changed |
oldStatus | the voucher's status before the change |
findVoucherById(Long id)
Returns: Voucher
Looks up a voucher belonging to the current tenant organisation by its internal ID.
| Parameter | Description |
|---|---|
id | the voucher's internal ID, or null |
toVoucherBean(Voucher voucher)
Returns: VoucherBean
Converts a voucher entity to its bean representation for use in templates.
| Parameter | Description |
|---|---|
voucher | the voucher to convert, or null |
createVouchers(VoucherType voucherType, Long numVouchers)
Returns: List<Voucher>
Creates a batch of new, unallocated vouchers of the given type, generating a unique voucher ID for each one.
| Parameter | Description |
|---|---|
voucherType | the voucher type to create vouchers for |
numVouchers | how many vouchers to create |
allocate(VoucherAllocationBuilder b)
Returns: Voucher
Executes an allocation request built with newVoucherAllocationBuilder(): allocates the builder's specific voucher if one was set, otherwise finds and allocates an available voucher of the builder's voucher type.
| Parameter | Description |
|---|---|
b | the populated builder describing the allocation |
findAvailableVoucher(VoucherType vt)
Returns: Voucher
Finds a single unallocated voucher of the given type, i.e. one with no status set yet.
| Parameter | Description |
|---|---|
vt | the voucher type to search |
findAvailableVoucher(VoucherType vt, List<Long> excludedVoucherIds)
Returns: Voucher
Finds a single unallocated voucher of the given type, i.e. one with no status set yet, ignoring any voucher whose ID is in excludedVoucherIds.
| Parameter | Description |
|---|---|
vt | the voucher type to search |
excludedVoucherIds | internal IDs of vouchers to exclude from the search |
allocate(Voucher voucher, Profile profile, String allocatedToId, String notes, Organisation redeemerOrg)
Returns: Voucher
Allocates a specific voucher to a profile, changing its status to allocated.
| Parameter | Description |
|---|---|
voucher | the voucher to allocate |
profile | the profile to allocate the voucher to |
allocatedToId | the identifier to record as the voucher's allocatedToId |
notes | notes to record against the allocation |
redeemerOrg | the organisation the voucher is allocated for redemption at |
generateIdFromTemplate(String voucherIdTemplate)
Returns: String
Evaluates an MVEL voucher ID template expression against this manager, to produce a voucher ID.
| Parameter | Description |
|---|---|
voucherIdTemplate | the MVEL template expression to evaluate |
randomHex(int numDigits)
Returns: String
Generates a random hexadecimal string of exactly the requested length.
| Parameter | Description |
|---|---|
numDigits | the required length of the returned string |
randomInt(int numDigits)
Returns: String
Generates a random numeric string of exactly the requested length, left-padded with zeros.
| Parameter | Description |
|---|---|
numDigits | the required length of the returned string |
statusText(String status)
Returns: String
Converts a voucher status code to human-friendly display text.
| Parameter | Description |
|---|---|
status | the status code to convert |
newVoucherAllocationBuilder(VoucherType type)
Returns: VoucherAllocationBuilder
Creates a new, empty allocation request builder for the given voucher type.
| Parameter | Description |
|---|---|
type | the voucher type to allocate from |
saveVoucherExtraFieldValues(Voucher voucher, Map<String,String> extraFieldValues)
Returns: void
Saves values for a voucher's extra (custom) fields, replacing its field set with a new one carrying the merged values, and fires the voucher-updated event if anything changed.
| Parameter | Description |
|---|---|
voucher | the voucher to update |
extraFieldValues | a map of extra field name to new value |
findVoucherExtraFieldValues(Voucher voucher)
Returns: Map<String,String>
Returns all extra (custom) field values currently set on the voucher.
| Parameter | Description |
|---|---|
voucher | the voucher to read extra field values from |
findVoucherTypeExtraFields(VoucherType voucherType)
Returns: List<ExtraField>
Returns the extra (custom) field definitions configured on the voucher type's fieldset, sorted by their ordering, falling back to name order for fields without an ordering set.
| Parameter | Description |
|---|---|
voucherType | the voucher type to read extra field definitions from |
deleteVoucher(Voucher voucher, Profile profile)
Returns: void
Soft-deletes a voucher and fires the voucher-deleted index event.
| Parameter | Description |
|---|---|
voucher | the voucher to delete |
profile | the profile performing the deletion, must not be null |
newVoucherTypeBuilder()
Returns: VoucherTypeBuilder
Creates a new, empty voucher type builder for creating or updating a voucher type.
newVoucherTypeBuilder(VoucherType voucherType)
Returns: VoucherTypeAllocationBuilder
Creates a new allocation request builder for the given voucher type.
| Parameter | Description |
|---|---|
voucherType | the voucher type to allocate from |
getVoucherStatusCodes()
Returns: Map<String,String>
Returns all defined voucher status codes and their human-readable descriptions.
newVoucherStatusBuilder(Voucher voucher)
Returns: VoucherStatusBuilder
Creates a new status-change builder for the given voucher.
| Parameter | Description |
|---|---|
voucher | the voucher to build a status change for |
© 2025 Kademi Ltd