Rule Action Reference¶

Lookup Member¶

This action looks up and populates member details for the current activity. Also, because resolving the member is usually the first action taken, checks for duplicate transactions by external transaction ID (activity.externalTxnId)

Parameters

None. Uses the current activity context.

JavaScript API

UDF.populateMember(callback)

Outputs

Populates Context with:

• member: The member object
• member.loyaltyIds: Array of loyalty IDs associated with the member
• activity.memberID: ID of the member
• activity.originalMemberID: Original member ID before any merges
• autoEnroll: Boolean indicating if member was autoenrolled

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Lookup sequence:
  • Tries to find member by memberID
  • If not found, tries to find by loyaltyID
  • If still not found and program autoEnroll setting exists, autoenrolls the member
• Supports autoenrollment into programs based on settings
• Updates the member structure version if needed (if new purses have been added, and so on)
• Handles member merges by resolving to survivor member if the activity was invoked with ?resolveMerge=true
• Validates that the member program matches activity program
• Checks for duplicate transactions by external transaction ID

Lookup Account Members¶

This action looks up and populates all members linked to the current member's account. Only returns members from the same program.

Parameters

None. Uses the current member context.

JavaScript API

UDF.populateAccountMembers(callback)

Outputs

Populates Context.linkedAccount with:

• members: Array of linked member objects from the same program
• _id: Account ID
• org: Organization ID
• activeMember: ID of the active member in the account

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Only returns members from the same program as the current member
• Automatically updates member structure version if needed
• Marks transitive properties on purse accruals, redemptions and escrows
• Returns empty members array if member has no linked account
• Populates full member details excluding:
  • events
  • activities
  • rewards
  • offers
  • segments
  • badges
  • memberSegments
  • preferences
  • pendingIds

Lookup Member Aggregates¶

This action looks up and populates aggregate metrics for the member across different time periods.

Parameters

JavaScript API

UDF.populateMemberAggregates(aggregates, types, fromDate, toDate, callback)

Outputs

Populates Context with aggregate data in:

• context[type + 'Aggs'] for each requested type (such as dailyAggs, weeklyAggs, and so on)

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Supports multiple aggregate types: daily, weekly, monthly, quarterly, halfyearly, yearly, lifetime
• Validates date ranges against the current activity date
• Returns empty results if no aggregates are found
• All dates are adjusted for timezone offset from the program settings (default time zone)

Update Member Aggregate¶

This action updates a member's aggregate value for a given policy.

Parameters

JavaScript API

There is no JS API for this action.

Outputs

Updates member's aggregate values in Context.aggregates.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates the numeric parameters (value)
• Filters policies by:
  • Available redemptions > 0
  • Expiration date >= activity date
  • Budget > 0 for offers
  • Cost <= balance (if balance provided)
• Applies location overrides if configured
• Calculates maximum possible discount for each policy
• Sorts results by discount amount (descending)
• Returns top N results if maxPolicies specified
• Handles both rewards and offers with budget constraints

Lookup Member Loyalty IDs¶

This action looks up and populates loyalty IDs associated with the current member.

Parameters

None. Uses the current member context.

JavaScript API

There is no JS API for this action.

Outputs

Populates Context.member.loyaltyIds with an array of loyalty ID objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns early if no member is found in the context
• Returns an empty array if no loyalty IDs are found

Lookup Merge Victims¶

This action finds all members that were merged into the current member (victims of merge operations).

Parameters

JavaScript API

UDF.populateMergeVictims(memberIds, callback)

Outputs

Populates Context.mergeVictim.members with an array of victim member objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns early if no context member is found (logs warning)
• If memberIds is provided, validates that each ID is a valid ObjectId
• Queries the mergetrail collection for victim records
• Excludes transient fields from victim member objects
• Returns silently if no merge victims are found

Add Points¶

This action accrues points to a Purse, usually to reward some Activity posted for the member. The action allows setting the Purse, points expiration date, escrow date and specifying the accounting type of the points. This is both a rule action and a user-defined function (UDF).

Parameters

Outputs

None

JavaScript API

UDF.addPoints(policyId, purseName, points, accountingType, expirationDate, escrowDate, cb)

Events Triggered

Generates the L2 AddPointsEvent when points are added.

Possible Errors

Additional Considerations

• In the Rule Builder the Purse Name is a drop-down, showing all the Purse Policies. You can select Variable if you would like to compute the Purse Name parameter at run-time.
• If points is 0, the operation is skipped
• Points can't be negative
• If the rule has countLimit or budget > 0, the rule context is updated
• To model floating point values (such as USD), use the lowest granularity (such as cents)

Redeem Points¶

This action redeems points from a member's purse. The action validates available balance before redemption and handles locked points appropriately.

Parameters

JavaScript API

UDF.redeemPoints(policyId, purseName, points, cb)

Events Triggered

Generates the L2 RedeemPointsEvent when points are redeemed.

Possible Errors

Additional Considerations

• In the Rule Builder, the Purse Name is a drop-down, showing all the Purse Policies. You can select Variable to compute the Purse Name parameter at run-time.
• If points is 0, the operation is skipped
• Points can't be negative
• Checks for the available balance before redeeming
• Considers locked points when calculating the available balance
• To model floating point values (such as USD), use the lowest granularity (such as cents)

Linked Add Points¶

This action adds points to multiple linked members' purses in a single operation. Points can be added with different amounts for each member, with optional accounting type, expiration date, and escrow date.

Parameters

Outputs

Returns array of updated purses.

JavaScript API

There is no JS API for this action.

Events Triggered

Generates the L2 AddPointsEvent for each member involved.

Possible Errors

Additional Considerations

• In the Rule Builder the Purse Name is a drop-down, showing all the Purse Policies. You can select Variable if you would like to compute the Purse Name parameter at run-time.
• If points is 0, operation is skipped
• Points can't be negative
• If rule has countLimit or budget > 0, rule context is updated
• When using array format, each object must have:
• memberId as key
• amount: points to add
• activity: activity object for the linked member
• For single member operations, points can be a simple number
• To model floating point values (such as USD), use the lowest granularity (such as cents)
• Activities are automatically created and added to linked members

Linked Redeem Points¶

Action to redeem points from multiple linked members' purses in a single transaction. This action ensures atomic updates across all involved members and validates points availability before redemption.

Parameters

JavaScript API

There is no JS API for this action.

Events Triggered

Generates the L2 RedeemPointsEvent for each member involved.

Possible Errors

Additional Considerations

• All member updates occur in a single transaction for consistency
• Points validation happens before any redemptions start
• Concurrent redemptions are detected and prevented
• Activity records are created for each member involved
• Points must be positive integers
• All members must belong to the same program

Targeted Redeem Points¶

This action redeems points from a specific activity's accruals.

Parameters

JavaScript API

There is no JS API for this action.

Events Triggered

Generates L2 RedeemPointsEvent when points are redeemed.

Possible Errors

Additional Considerations

• Validates that the target activity ID is valid ObjectId
• Validates that the purse exists and belongs to member
• Checks the available points in the target activity's accruals
• Cannot redeem more points than available in the target activity
• Points can't be redeemed after the purse period close date
• Generates events before the database updates
• Updates both the purse balance and accrual records

Lock Points¶

This action locks points in a purse until a specified date.

Parameters

JavaScript API

UDF.lockPoints(policyId, points, lockedTill, tag, callback)

Events Triggered

• Generates L2 LockPointsEvent when points are locked

Possible Errors

Additional Considerations

• Validates that the purse exists and belongs to the member
• Points must be a positive number
• Locked till date must be in the future
• Points can't be locked after the purse period close date
• Total locked points can't exceed purse balance

Unlock Points¶

This action unlocks previously locked points in a purse.

Parameters

JavaScript API

UDF.unlockPoints(policyId, lookupField, lookupValue, callback)

Events Triggered

• Generates L2 UnlockPointsEvent when points unlocked

Possible Errors

Additional Considerations

• Validates that the lookup field and value are provided
• Validates that the purse exists and belongs to member
• Can't unlock points after the purse period close date
• Updates the locked points array in the purse
• Returns the unlocked points records in the result
• Supports multiple lock records matching the lookup criteria
• Lookup field and value can be comma-separated for multiple matches

Expire Balance¶

This action expires the balance in a purse.

Parameters

JavaScript API

UDF.expireBalance(purseId, purseName, callback)

Possible Errors

Additional Considerations

• Validates purse exists before expiring balance
• Purse Name parameter is only used when Purse is set to 'Variable'
• Expires all eligible accruals in the purse
• Updates purse balance after expiration

Expire Accruals¶

This action expires the balance associated with accruals that have reached their expiration date within a purse.

Parameters

JavaScript API

UDF.expireAccruals(purseId, purseName, availableBalance, lastActivityDate, pointsToExpire,
        evaluateExpiredPoints, callback)

Possible Errors

Additional Considerations

• Validates purse exists before expiring balance
• Purse Name parameter is only used when Purse is set to 'Variable'
• Expires all eligible accruals in the purse
• Updates purse balance after expiration

Escrow Activity¶

This action escrows points from a previous activity.

Parameters

JavaScript API

UDF.escrowActivity(externalTxnId, transactionId, purseId, purseName, value, callback)

Events Triggered

No events are generated by this action

Possible Errors

Additional Considerations

• At least one of External Txn Id or Transaction Id must be provided
• Purse Name is only valid when Purse is set to 'Variable'
• Original activity must exist and be in a valid state for escrow

Transfer In¶

This action transfers points from a transfer member to the context member.

Context Member

The context member refers to the member to whom the activity is being posted. This member receives the points transferred from another member.

Transfer Member

The transfer member is dynamically loaded based on the Lookup Field provided in the rule action. This member is the source of the points that are getting transferred.

Parameters

JavaScript API

There is no JS API for this action.

Execution Details

Context Member

The same activity is used to create the accrual using the points provided in the Points parameter.

Transfer Member Activity

The transfer member is fetched using the Lookup Field parameter. A new activity is created for the transfer member with the following payload:

{
  "type": "Transfer Out",
  "date": context.activity.utcDate || new Date(),
  "currencyCode": context.activity.currencyCode,
  "memberID": transferMember._id,
  "originalMemberID": transferMember._id,
  "srcChannelID": context.activity.srcChannelID,
  "srcChannelType": context.activity.srcChannelType,
  "value": context.activity.value,
  "status": "Processed",
  "result": {
    "data": {
      "purses": [
        {
          "name": "<Purse Name>",
          "prev": "<Balance before this action execution>",
          "prevAvail": "<Available Balance before this action execution>",
          "new": "<Balance after this action execution>",
          "newAvail": "<Available Balance after this action execution>"
        }
      ]
    }
  }
}

Error Handling

Member Not Found

• If member_id is used and no matching member is found:

  Error Message: No member found with memberId "%s" in program "%s".

• If loyaltyid is used and no matching member is found:

  Error Message: No member found with loyaltyID "%s" in program "%s".

Transfer Member is the Same as Context Member

• If the transfer member is the same as the context member:

  Error Message: The target member must not be same as the source member.

Transfer Out¶

This action transfers points from the context member to a transfer member.

Context Member

The context member refers to the member to whom the activity is being posted. This member gives the points to another member.

Transfer Member

The transfer member is dynamically loaded based on the Lookup Field provided in the rule action. This member is the recipient of the transferred points.

Parameters

JavaScript API

There is no JS API for this action.

Execution Details

Context Member

The same activity is used to create the redemption using the points provided in the Points parameter.

Transfer Member Activity

The transfer member is fetched using the Lookup Field parameter. A new activity is created for the transfer member with the following payload:

{
  "type": "Transfer In",
  "date": context.activity.utcDate || new Date(),
  "currencyCode": context.activity.currencyCode,
  "memberID": transferMember._id,
  "originalMemberID": transferMember._id,
  "srcChannelID": context.activity.srcChannelID,
  "srcChannelType": context.activity.srcChannelType,
  "value": context.activity.value,
  "status": "Processed",
  "result": {
    "data": {
      "purses": [
        {
          "name": "<Purse Name>",
          "prev": "<Balance before this action execution>",
          "prevAvail": "<Available Balance before this action execution>",
          "new": "<Balance after this action execution>",
          "newAvail": "<Available Balance after this action execution>"
        }
      ]
    }
  }
}

Error Handling

Member Not Found

• If member_id is used and no matching member is found:

  Error Message: No member found with memberId "%s" in program "%s".

• If loyaltyid is used and no matching member is found:

  Error Message: No member found with loyaltyID "%s" in program "%s".

Transfer Member is the Same as Context Member

• If the transfer member is the same as the context member:

  Error Message: The target member must not be same as the source member.

Transfer Accruals¶

This action transfers usable accruals from the source member to a target member.

Parameters

JavaScript API

There is no JS API for this action.

Execution Details

Source Member

• Retrieve usable accruals of the source member(contex member).
• Calculates the total available points from usable accruals to transfer.
• Creates a single packaged redemption transaction with the total available points to mark exisiting accruals as used.

Target Member

• Duplicates the source member accruals to the target member to ensure that the earn and expiration dates are accurately replicated.
• Updates the target member’s purse by adding the transferred points.
• Create a new activity on the target member, with type Transfer Accruals.

{
  "type": "Transfer Accruals",
  "date": context.activity.utcDate || new Date(),
  "currencyCode": context.activity.currencyCode,
  "memberID": targetMember._id,
  "originalMemberID": targetMember._id,
  "srcChannelID": context.activity.srcChannelID,
  "srcChannelType": context.activity.srcChannelType,
  "value": context.activity.value,
  "status": "Processed",
  "result": {
    "data": {}
  },
  "_internal": {
    "primaryActivityId": context.activity._id
  }
}

Possible Errors

Give Reward¶

This action adds a reward to a member based on a reward policy. The reward can be configured with a custom code, usage limits, and expiration date. The reward's configuration is determined by the specified reward policy.

Parameters

Outputs

Returns the created reward object.

JavaScript API

UDF.addReward(policyId, rewardCode, rewardCounter, checkLimit, expirationDate, cb)

Events Triggered

• Generates L1 ObjectInsertEvent when creating new reward
• Generates L2 AddRewardEvent when reward is added to member

Possible Errors

Additional Considerations

• If checkLimit is false, reward limit validation errors are logged but not thrown
• If no rewardCode is provided, a UUID is automatically generated
• If no expirationDate is provided, it's calculated based on the policy's expirationHours and expirationSnapTo settings
• If policy.availableRedemptions <= 0, throws an error
• Reward's usesLeft defaults to policy.numUses if not specified
• Reward's upc defaults to policy.upc if not specified
• Validates the member status against policy.applicableMemberStatus if configured
• Validates that the member program matches policy program
• Validates the policy effectiveDate and expirationDate
• Automatically sets the reward type to 'Reward'
• Sets the reward name from the policy name
• If the special flag 'allowFutureEffective' is enabled, the policy effective date validation is skipped
• If the special flag 'ignoreDoubleApply' is enabled, uses left validation is skipped
• If the special flag 'ignoreUsesLeft' is enabled, uses left validation is skipped

Give Specific Reward¶

This action gives a specific reward to a member.

Parameters

JavaScript API

UDF.addSpecificReward(rewardObj, checkLimit, rewardCounter, callback)

Events Triggered

• Generates L2 AddRewardEvent when reward is added
• Generates L1 ObjectInsertEvent when creating new reward

Possible Errors

Additional Considerations

• If checkLimit is false, limit-related errors are ignored
• Validates that the reward policy belongs to the member's program
• Validates that the reward policy is within its effective period unless canPreview is true
• Reward object must include the name and program fields
• If reward code is provided and already exists, a new code will be generated

Give Reward by Name¶

This action gives a reward to a member by name.

Parameters

JavaScript API

UDF.giveRewardByName(rewardName, rewardCode, rewardCounter, checkLimit, expirationDate, callback)

Events Triggered

• Generates L1 ObjectInsertEvent when creating new reward
• Generates L2 AddRewardEvent when reward is added

Possible Errors

Additional Considerations

• If checkLimit is false, limit-related errors are ignored
• Validates that the reward belongs to the member's program
• Validates that the reward is within its effective period unless canPreview is true
• Expiration date must be after the effective date if provided

Give Reward by UPC¶

This action gives a reward to a member using UPC code.

Parameters

JavaScript API

There is no JS API for this action.

Events Triggered

• Generates L1 ObjectInsertEvent when creating new reward
• Generates L2 AddRewardEvent when reward is added

Possible Errors

Additional Considerations

• If checkLimit is false, limit-related errors are ignored
• Validates that the reward belongs to the member's program
• Validates that the reward is within its effective period unless canPreview is true
• Expiration date must be after the effective date if provided
• External fields are merged into the reward object

Cancel Reward¶

This action cancels a reward by its code.

Parameters

JavaScript API

UDF.cancelReward(rewardCode, allowExpired, allowUsed, callback)

Events Triggered

• Generates L2 RewardReversalEvent when reward is cancelled

Possible Errors

Additional Considerations

• Validates that the reward exists before canceling
• Checks the reward expiration status if allowExpired is false
• Checks the reward usage status if allowUsed is false
• Can't cancel rewards that are currently locked

Lock Reward¶

This action locks a reward until a specified date, preventing it from being used until after that date.

Parameters

JavaScript API

UDF.lockReward(rewardCode, lockedTill, transactionId, callback)

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates that the reward exists and belongs to the member
• Locked till date must be in the future
• Can't lock cancelled rewards
• Can't lock expired rewards
• Can't lock rewards that aren't yet effective
• Transaction ID must be valid if provided

Unlock Reward¶

This action unlocks a previously locked reward.

Parameters

JavaScript API

UDF.unlockReward(lookupField, lookupValue, lockTxnId, callback)

Events Triggered

• Generates L2 UnlockRewardEvent when reward is unlocked

Possible Errors

Additional Considerations

• Validates that the reward exists and belongs to member
• Validates that the reward isn't cancelled, expired, or not yet in effect
• Lock transaction ID must match the one used when locking
• Updates the reward's locked till date to null
• Returns silently if the reward is already unlocked
• Can't unlock rewards that have been used

Lock Recent Reward By Type¶

This action locks the most recently issued reward of a specific type until a specified date.

Parameters

JavaScript API

UDF.lockRecentRewardByType(rewardType, lockedTill, options, callback)

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates that the reward type is provided
• Locked till date must be in the future
• Can't lock cancelled rewards
• Can't lock expired rewards
• Can't lock rewards that aren't yet effective
• Finds and locks the most recently issued reward matching the type

Use Recent Reward By Type¶

Uses the most recently assigned reward of the specified type. This action is used to redeem the latest reward that matches the given type.

Parameters

JavaScript API

UDF.useRecentRewardByType(type)

Events Triggered

Generates the L2 UseRecentRewardByTypeEvent.

Possible Errors

Additional Considerations

• The reward must be assigned to the member before it can be used
• The reward must be within its effective dates
• The reward must not have exceeded its maximum uses
• The reward must not be cancelled
• Only the most recently assigned reward of the specified type is used
• The reward type is case sensitive
• If multiple rewards of the same type exist, the most recently assigned one is used

Use Reward By Code¶

Uses a reward by its code. This action redeems a reward that was assigned to a member using a code.

Parameters

JavaScript API

UDF.useRewardByCode(code)

Events Triggered

Generates the L2 UseRewardByCodeEvent.

Possible Errors

Additional Considerations

• The reward must be assigned to the member before it can be used
• The reward must be within its effective dates
• The reward must not have exceeded its maximum uses
• The reward must not be cancelled

Give Offer by Lookup Field¶

This action gives an offer to a member using lookup field.

Parameters

JavaScript API

UDF.giveOfferByLookup(lookupField, lookupValue, offerCode, offerCounter, checkLimit, expirationDate, futureEffective, callback)

Events Triggered

• Generates L1 ObjectInsertEvent when creating new offer
• Generates L2 AddOfferEvent when offer is added

Possible Errors

Additional Considerations

• If checkLimit is false, limit-related errors are ignored
• Validates offer belongs to member's program
• Validates offer is within its effective period unless canPreview is true or special flag of futureEffective is true
• Expiration date must be after the effective date if provided

Give Offer by Lookup Field With Params¶

This action gives an offer to a member using lookup field and additional parameters.

Parameters

JavaScript API

UDF.giveOfferByLookupWithParams(lookupField, lookupValue, params, offerCounter, checkLimit, callback)

Events Triggered

• Generates L1 ObjectInsertEvent when creating new offer
• Generates L2 AddOfferEvent when offer is added

Possible Errors

Additional Considerations

• If checkLimit is false, limit-related errors are ignored
• Params object can include custom fields that will be added to the offer
• Validates that the offer belongs to the member's program
• Validates that the offer is within its effective period unless canPreview is true

Lock Offer¶

This action locks an offer until a specified date.

Parameters

JavaScript API

UDF.lockOffer(lookupField, lookupValue, lockedTill, lockTxnId, callback)

Events Triggered

• Generates L2 LockOfferEvent when offer is locked

Possible Errors

Additional Considerations

• Validates that the offer exists and belongs to the member
• Validates that the offer isn't already used, cancelled, or expired
• Can't lock global offers or multi-use offers
• Lock transaction ID is required and must be valid
• Locked till date must be valid and in the future

Unlock Offer¶

This action unlocks a previously locked offer.

Parameters

JavaScript API

UDF.unlockOffer(lookupField, lookupValue, lockTxnId, callback)

Events Triggered

• Generates L2 UnlockOfferEvent when offer is unlocked

Possible Errors

Additional Considerations

• Validates that the offer exists and belongs to member
• Validates that the offer isn't cancelled, expired, or not yet in effect
• Can't unlock global offers or multi-use offers
• Lock transaction ID is required and must be valid
• Must match the transaction ID used when locking
• Updates offer's locked till date to null

Use Offer By Code¶

Uses an offer by its code. This action redeems an offer that was assigned to a member using a code.

Parameters

Outputs

None

JavaScript API

UDF.useOfferByCode(code)

Events Triggered

Generates the L2 UseOfferEvent.

Possible Errors

Additional Considerations

• The offer must be assigned to the member before it can be used
• The offer must be within its effective dates
• The offer must not have exceeded its maximum uses
• The offer must not be cancelled

Apply Offers¶

This action applies the best offers to the current activity based on the activity's best offers list.

Parameters

JavaScript API

UDF.applyOffers(ignoreMissing, callback)

Events Triggered

• Generates L2 UseOfferByCodeEvent for each offer applied
• Generates L2 UseRewardByCodeEvent for each reward applied

Possible Errors

Additional Considerations

• Uses the activity's bestOffers list to determine which offers to apply
• If ignoreGlobalOffer is false, throws an error when global offer policies aren't found
• If ignoreOffer is false, throws an error when an offer isn't found for the member
• If ignoreReward is false, throws an error when a reward isn't found for the member
• Validates offer effective dates and expiration dates before applying

Check Offer Limits¶

This action checks if a member has exceeded offer or reward limits based on configured thresholds.

Parameters

Outputs

Sets Context.limitExceeded to true if any limit is exceeded, false otherwise.

JavaScript API

UDF.checkOfferLimits(entityType, policyFilter, limits, isCalendar, callback)

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Supports daily, weekly, and monthly limits
• Week boundaries determined by program's weekStartDay setting
• Calendar mode uses fixed month/week boundaries
• Non-calendar mode uses rolling periods
• Checks both transient and stored records

Update Member Offer With Params¶

This action applies the provided lookups and offer filter to identify relevant member offers and updates their attributes.

Parameters

Outputs

The updates are applied to each member offer record filtered using the provided lookup fields and values. If an offer filter is provided and its key matches a lookup field, the filter conditions are combined with the existing lookups; otherwise, the filter is applied alongside the existing criteria.

JavaScript API

UDF.updateMemberOfferWithParams(lookupField, lookupValue, offerFilter, offerObj, callback)

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• The offer must be assigned to the member before its attributes can be updated
• Returns silently if the offer matching the filters isn't found
• Sets the updatedAt and updatedBy fields automatically
• Updates the attributes of the member's offer based on the applied filters

Assign Promo Code¶

This action assigns a promo code from a campaign to a member.

Parameters

JavaScript API

UDF.assignPromoCode(campaignCode, callback)

Events Triggered

• Generates L1 ObjectUpdateEvent

Possible Errors

Additional Considerations

• Validates that the campaign exists and is within its effective period
• Updates the promo code status from 'New' to 'Assigned'
• Sets the assignment date to the current time
• Validates that the campaign belongs to the member's program

Redeem Promo Code¶

This action redeems a promo code that has been assigned to the member.

Parameters

JavaScript API

UDF.redeemPromoCode(promoCode, callback)

Outputs

Populates Context.result.data.promoCodes with array containing the redeemed promo code object.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates that the promo code exists and is assigned to member
• Checks the campaign start and end dates
• Updates the promo code status to 'Redeemed'
• Sets the redemption date to the current activity date
• Updates the context with the redeemed code details
• Combines with any existing promo codes in context

Assign And Redeem Promo Code¶

This action assigns and immediately redeems a promo code in a single operation.

Parameters

JavaScript API

UDF.assignAndRedeemPromoCode(promoCode, callback)

Events Triggered

• Generates L1 ObjectUpdateEvent

Possible Errors

Additional Considerations

• Validates that the promo code exists and is in 'New' status
• Updates the promo code status directly from 'New' to 'Redeemed'
• Sets both assignment and redemption dates to the current time
• Validates that the campaign belongs to the member's program

Lookup Activities¶

This action looks up and populates activities for the current member within a specified date range.

Parameters

JavaScript API

UDF.populateActivities(fromDate, limit, status, type, callback)

Outputs

Populates Context.member.activities with an array of activity objects.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• If fromDate isn't provided, it defaults to the start of the current day
• Activities are filtered by member ID and original member ID (unless disOriginalMemIdHisLookup is enabled)
• Activities are filtered to be between fromDate and the current activity date
• Respects program setting disOriginalMemIdHisLookup to control whether to lookup by original member ID
• Status parameter can be a comma-separated list of statuses to filter by

Lookup Activity By ID¶

This action looks up and populates a specific activity by its ID.

Parameters

JavaScript API

UDF.populateActivityById(activityId, callback)

Outputs

Populates Context.member.activities array with the found activity object.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns immediately if activity ID is invalid or not provided
• Returns silently if the activity isn't found

Lookup Activity By Params¶

This action looks up and populates activities matching specified parameters.

Parameters

JavaScript API

UDF.populateActivityByParams(lookupField, lookupValue, callback)

Outputs

Populates Context.member.activities with matching activity objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns immediately if lookup field or value isn't provided
• Returns silently if no matching activities are found
• Supports multiple lookup fields and values as comma-separated lists
• Values must match in order with their corresponding lookup fields

Cancel Transaction¶

This action cancels a previous transaction by either its activity ID or external transaction ID.

Parameters

JavaScript API

UDF.cancelTransaction(lookupField, value, callback)

Events Triggered

• Generates L2 CancelActivityEvent when transaction is cancelled

Possible Errors

Additional Considerations

• Reverses all point transactions from the original activity
• Cancels any rewards or offers that were issued
• Updates the original activity status to indicate cancellation
• Maintains an audit trail of the cancellation

Create Metric Event¶

This action creates a metric event for aggregating member data.

Parameters

The Event Payload object must contain:

{
  name: string,         // The name of the metric being populated
  aggregates: string,   // Comma separated list of aggregates to populate (daily, weekly, monthly, quarterly, halfyearly, yearly, lifetime)
  value: number,        // Value to be recorded for the metric
  date: Date,          // Optional. The date for recording the metric. Defaults to activity date
  expirationDate: Date // Optional. When the metric expires
}

JavaScript API

There is no JS API for this action.

Events Triggered

• Generates L2 MetricEvent when metric is created

Possible Errors

Additional Considerations

• Supports daily, weekly, monthly, quarterly, halfyearly, yearly, and lifetime aggregates
• Multiple aggregate types can be specified in a comma-separated list
• Date values are validated before processing
• Value is rounded to 0 if not provided or invalid

Generate Custom Event¶

This action generates a custom event with the provided data.

Parameters

JavaScript API

UDF.generateCustomEvent(data, callback)

Events Triggered

• Generates L2 CustomActionEvent with the provided data as payload

Possible Errors

This action doesn't throw any errors.

Additional Considerations

• Only generates an event if data is provided and not empty
• Event includes the user ID and member ID in the header
• Creates member.events array if it doesn't exist

Lookup Activity Offers¶

This action looks up and populates offer coupons associated with the current activity.

Parameters

None. Uses the current activity context.

JavaScript API

UDF.populateActivityCouponOffers(callback)

Outputs

Populates the current activity with:

• activity.coupon: The main activity coupon if activity.couponCode exists
• activity.lineItems[].coupon: Individual line item coupons if lineItems[].couponCode exists

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Looks up coupons by code from the Offer collection
• Only returns coupons with usesLeft > 0
• Sorts by the expiration date when multiple matches exist
• Attaches coupons to both the activity level and the line item level
• Returns silently if no matching coupons are found

Lookup Activity Rewards¶

This action looks up and populates reward coupons associated with the current activity.

Parameters

None. Uses the current activity context.

JavaScript API

UDF.populateActivityCouponRewards(callback)

Outputs

Populates the current activity with:

• activity.coupon: The main activity coupon if activity.couponCode exists and mathes the Reward code
• activity.lineItems[].coupon: Individual line item coupons if lineItems[].couponCode exists and matches the Reward code

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Looks up coupons by code from the Reward collection
• Only returns coupons with usesLeft > 0
• Sorts by the expiration date when multiple matches exist
• Attaches coupons to both the activity level and the line item level
• Returns silently if no matching coupons are found

Lookup Applicable Offers¶

This action finds all applicable offers for the current activity and member.

Parameters

JavaScript API

UDF.populateApplicableOffers(filterOfferTypes, policyFilter, lineItemFilter, options, populateFields, callback)

Populates Context.result.data.applicableOffers with array of applicable offers/rewards.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Validates all offers/rewards exist and are usable
• Checks the offers/rewards cancellation status
• Verifies the offers/rewards effective dates
• Validates the remaining offers/rewards uses
• Handles both global and member-specific offers (wallet offers/rewards)
• Supports offer budget constraints
• Applies location overrides if configured
• Serializes line items if SPECIAL_FLAGS includes 'serializeLineItems'

Lookup Best Offers¶

This action finds the best applicable offers for the current activity and member.

Parameters

JavaScript API

UDF.populateBestOffers(populateFields, offerFilter, lineItemFilter, options, callback)

Outputs

Populates Context.result.data with: - bestOffers: Array of best applicable offers - repricedTicket: Activity with applied discounts - applicableOffers: Array of all applicable offers

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Validates that all offers exist and are usable
• Checks the offer cancellation status
• Verifies the offer effective dates
• Validates the remaining offer uses
• Handles both global and member-specific offers (wallet offers)
• Supports offer budget constraints
• Applies location overrides if configured
• Optimizes offer combinations for maximum discount
• Serializes line items if SPECIAL_FLAGS includes 'serializeLineItems'

Lookup Best Offer Policies¶

This action looks up and populates offer policies corresponding to best offers.

Parameters

JavaScript API

There is no JS API for this action.

Outputs

Updates best offers in Context.activity.bestOffers with resolved policy IDs.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates lookup field is provided
• Looks up policies by the specified field
• Updates originalPolicyId and policyId in best offers
• Logs missing policies if ignoreMissing is true
• Only processes global offers that don't already have originalPolicyId

Lookup Contextual Reward Policies¶

This action finds applicable reward policies based on the current activity context, optionally filtered by type and balance requirements.

Parameters

JavaScript API

UDF.promptApplicablePolicies(lookupField, lookupValue, policyFilter, lineItemExclusionFilter, balance, maxPolicies, callback)

Outputs

Populates Context.result.data.applicablePolicies with array of:

• policy: The reward policy object
• discountAmount: Maximum possible discount for this policy

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates numeric parameters (balance, maxPolicies)
• Filters policies by:
  • Available redemptions > 0
  • Expiration date >= activity date
  • Budget > 0 for offers
  • Cost <= balance (if balance provided)
• Applies location overrides if configured
• Calculates maximum possible discount for each policy
• Sorts results by discount amount (descending)
• Returns top N results if maxPolicies is specified
• Handles both rewards and offers with budget constraints

Lookup Eligible Offers¶

This action finds all eligible offers for the current activity and member based on policy and line item filters.

Parameters

JavaScript API

UDF.getEligibleOffers(policyFilter, offerFilter, lineItemFilter, callback)

Outputs

Populates Context with:

• eligibleOffers: Array of eligible offers
• eligibleRewardPolicies: Array of eligible reward policies with applicable product lines

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Filters offers based on:
  • Member's program
  • Location overrides if configured
  • Policy criteria if provided
  • Line item criteria if provided
• Calculates applicable product lines for each reward policy
• Handles different discount types:
  • Ticket
  • Mix and Match
  • Combo
  • ComboList
• Supports filtering by:
  • Regular offers
  • Reward offers
  • Global offers
• Logs debug information about policy filtering and location overrides

Lookup Enums¶

This action looks up and populates enums of specified types.

Parameters

JavaScript API

UDF.populateEnums(enumTypes, callback)

Outputs

Populates Context.activityEnums with array of matching enum objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• If no enum types are provided, logs a debug message and returns
• Filters enums by language 'en'
• Combines with any existing enums in Context.activityEnums
• Uses cached enum data when available
• Returns all enums if no types are specified
• Deduplicates enum values using Set

Lookup Linked Member Offers¶

This action looks up and populates offers for all members linked to the current member's account.

Parameters

JavaScript API

UDF.populateLinkedMemberOffers(fromDate, usable, callback)

Outputs

Populates each linked member in Context.linkedAccount.members with:

• offers: Array of offer objects

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Filters offers by:
  • Member ID from linked members array
  • From date if provided
  • Usable status (not cancelled, has uses left, not expired) if usable=true
  • Custom filter criteria if usable is an object
• Marks all loaded offers as transitive
• Combines offers from both database and member's transient data
• Skips loading if linked members aren't populated

Lookup Linked Member Rewards¶

This action looks up and populates rewards for all members linked to the current member's account.

Parameters

JavaScript API

UDF.populateLinkedMemberRewards(fromDate, usable, callback)

Outputs

Populates each linked member in Context.linkedAccount.members with:

• rewards: Array of reward objects

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Filters rewards by:
  • Member ID from linked members array
  • From date if provided
  • Usable status (not cancelled, has uses left, not expired) if usable=true
  • Custom filter criteria if usable is an object
• Marks all loaded rewards as transitive
• Combines rewards from both database and member's transient data
• Skips loading if linked members aren't populated

Lookup Location¶

This action looks up and populates location information for the current activity.

Parameters

JavaScript API

UDF.populateLocation(lookupFields, callback)

Outputs

Populates Context.activity with:

• location: The matched location object
• utcOffset: Timezone offset from location or program default
• utcDate: Activity date adjusted for timezone

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• If no lookup fields are provided, matches on activity.srcChannelID
• Uses location timezone if available, otherwise uses the program's default UTC offset
• Sets activity.utcDate based on the timezone offset
• Handles location overrides for rules if configured
• Returns silently if no matching location is found

Lookup Member Offers¶

This action looks up and populates offers associated with the current member.

Parameters

JavaScript API

UDF.populateMemberOffers(fromDate, usable, callback)

Outputs

Populates Context.member.offers with array of offer objects.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Filters offers by:
  • Member ID
  • From date if provided
  • Usable status (not cancelled, has uses left, not expired) if usable=true
  • Custom filter criteria if usable is an object
• Marks all loaded offers as transitive
• Returns an empty array if no offers are found

Lookup Member Preferences¶

This action looks up and populates preferences for the current member.

Parameters

JavaScript API

UDF.populateMemberPreferences(name, callback)

Outputs

Populates Context.member.preferences with array of preference objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns early if preference already exists in member.preferences
• Filters preferences by:
  • Member ID
  • Expiration date > current date
  • Preference name if provided
• Handles cancelled preferences by removing them from results
• Returns an empty array if no preferences are found

Lookup Member Rewards¶

This action looks up and populates rewards associated with the current member.

Parameters

JavaScript API

UDF.populateMemberRewards(fromDate, usable, callback)

Outputs

Populates Context.member.rewards with array of reward objects.

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Filters rewards by:
  • Member ID
  • From date if provided
  • Usable status (not cancelled, has uses left, not expired) if usable=true
  • Custom filter criteria if usable is an object
• Marks all loaded rewards as transitive
• Returns an empty array if no rewards are found

Lookup Partner¶

This action looks up and populates partner information for the current activity.

Parameters

JavaScript API

UDF.populatePartner(partnerCode, callback)

Outputs

Populates Context.activity.partner with the partner object

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• If no partner code is provided, uses activity.partnerCode
• Returns early if a partner code isn't provided
• Returns silently if the partner isn't found
• Excludes internal fields from the returned partner object
• Supports passing partner object directly instead of code

Lookup Products¶

This action looks up and populates product information for activity line items.

Parameters

JavaScript API

UDF.populateProducts(applyTo, lookupFields, callback)

Outputs

Populates Context with:

• activityProducts: Array of products with line numbers and quantities
• Updates line items in activity or repricedTicket with product information

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• If no lookup fields are provided, uses 'sku:itemSKU' as default
• Supports productId lookup if line items have the productId field
• Validates product effective dates against the activity date
• Handles missing products by using 'Missing Product' placeholder if available
• Combines line item data with product data
• Supports custom lookup field mappings (such as 'name:type') where the first field is a field in lineItem and the second is part of the Product
• Values must match in order with their corresponding lookup fields

Lookup Promo Codes¶

This action looks up and populates promo codes for the current activity.

Parameters

JavaScript API

There is no JS API for this action.

Outputs

Populates target (or Context.result.data) with:

• promoCodes: Array of promo code objects with their definitions

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Validates promo codes parameter is provided
• Queries both PromoCode and PromoCodeDef collections
• Returns empty array if no matching codes found
• Supports both single code string and array of codes
• Populates definition details for each code

Lookup Promo Limits¶

This action looks up and populates promotion rule limits for the current activity.

Parameters

None. Uses the current activity context.

JavaScript API

There is no JS API for this action.

Outputs

Populates Context.promoRuleLimits with:

• Object mapping rule IDs to their limit objects
• Each limit contains: rule, redemptions, availableRedemptions, budgetUsed, availableBudget

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Filters limits by:
  • Program from context member
  • Not trashed
  • Effective dates:
    • effectiveTo is null or >= activity date
    • canPreview is true or effectiveFrom <= activity date
• Returns an empty object if no limits are found
• Organizes limits by rule ID for easy lookup
• Supports preview mode through the canPreview flag

Lookup Purse Policies¶

This action looks up and populates purse policies based on lookup criteria.

Parameters

JavaScript API

UDF.populatePursePolicies(lookupField, lookupValues, pursePolicyFilter, callback)

Outputs

Populates `Context.pursePolicies1 with array of purse policy objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• If lookup values are provided but not in an array, splits on the comma
• Trims whitespace from lookup values
• Combines lookup field filter with any additional filter criteria
• Always filters by program from the context member
• Returns an empty array if no policies are found
• Combines with any existing purse policies in context
• Uses Map to deduplicate policies by ID

Lookup Reward Policies¶

This action looks up and populates reward policies based on lookup criteria.

Parameters

JavaScript API

UDF.populateRewardPolicies(lookupField, lookupValues, selectFields, callback)

Outputs

Populates Context.activity.rewardPolicies with array of reward policy objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Returns early if the lookup field isn't provided
• If lookup values are provided but not in an array, splits on the comma
• Trims whitespace from lookup values
• Returns an empty array if no policies are found
• Combines with any existing reward policies in the context
• Uses Map to deduplicate policies by ID
• Supports field selection to limit returned data

Lookup Tier History¶

This action looks up and populates tier history records for the current member.

Parameters

None. Uses the current member context.

JavaScript API

UDF.populateTierHistory(callback)

Outputs

Populates Context.member.tierHistory with array of tier history objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• Filters the tier history by member ID
• Combines with any existing tier history in the context
• Returns an empty array if no history is found
• Uses concat to preserve the order of history records

Lookup Tier Policies¶

This action looks up and populates tier policies based on lookup criteria.

Parameters

JavaScript API

UDF.populateTierPolicies(lookupField, lookupValues, selectFields, callback)

Outputs

Populates Context.tierPolicies with array of tier policy objects.

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• If lookup values are provided but not in an array, splits on the comma
• Trims whitespace from lookup values
• Returns an empty array if no policies are found
• Combines with any existing tier policies in the context
• Uses Map to deduplicate policies by ID
• Supports field selection to limit returned data

Lookup User¶

This action looks up and populates user information for the current context.

Parameters

None. Uses the current user context.

JavaScript API

UDF.populateUser(callback)

Outputs

Populates Context.user with a user object, excluding any sensitive fields (such as password, and so on).

Events Triggered

No events are generated by this action.

Possible Errors

Additional Considerations

• Returns early if no user is in the context
• Excludes sensitive fields from the returned user object
• Sets Context.user.id to user._id

Lookup Qualified Purses¶

This action looks up and populates qualified purses based on lookup criteria.

Parameters

JavaScript API

UDF.lookupQualifiedPurses(groupNames, callback)

Outputs

Populates Context.qPurses with object key is group name and corresponding value is the qualified purse name.

qPurses: {
    "Qualifying Nights": "Qualifying Nights 2025",
    "Qualifying Spend": "Qualifying Spend 2025"
}

Events Triggered

No events are generated by this action.

Possible Errors

No errors are thrown directly by this action. Any errors that occur are database errors propagated from the underlying MongoDB operations.

Additional Considerations

• It retrieves qualified purses based on the selected groups.
• If no group names are selected, it fetches qualified purses from all groups within the program and assigns them to the qPurses in the context.

Add Segment¶

This action adds a segment to a member. Segments are used to group members based on defined criteria.

Parameters

Outputs

Returns the added segment object.

JavaScript API

UDF.addSegment(segmentId, callback)

Events Triggered

• Generates L1 ObjectInsertEvent when creating or updating segment record
• Generates L2 AddSegmentEvent when segment is added to member

Possible Errors

Additional Considerations

• In the Rule Builder the Segment name is a drop-down, showing all the Segments. You can select Variable if you would like to compute the Segment Name parameter at run-time.
• Events are generated before database updates
• Updates member document with new segment
• Validates segment exists in program before adding

Remove Segment¶

This action removes a segment from a member.

Parameters

Outputs

Returns the removed segment object.

JavaScript API

UDF.removeSegment(segmentId, callback)

Events Triggered

• Generates L1 ObjectDeleteEvent
• Generates L2 RemoveSegmentEvent

Possible Errors

Additional Considerations

• In the Rule Builder the Segment name is a drop-down, showing all the Segments. You can select Variable if you would like to compute the Segment Name parameter at run-time.
• Updates member document to remove the segment
• Validates segment exists before removing

Add Preference¶

This action adds a preference to a member. Preferences can be configured with optional expiration dates and categories.

Parameters

Outputs

Returns the created preference object.

JavaScript API

UDF.addPreference(prefName, prefValue, optinDate, expirationDate, category, callback)

Events Triggered

• Generates L1 ObjectInsertEvent when creating or updating preference
• Generates L2 AddPreferenceEvent when preference is added to member

Possible Errors

Additional Considerations

• If no category is provided, defaults to 'Preference'
• Preferences are stored in a separate collection and linked to the member
• Updates existing preference if name already exists for member
• Automatically sets creation and update timestamps
• Events are generated before database updates
• Member document is updated to remove processed preferences

Remove Preference¶

This action removes a preference from a member by its name.

Parameters

Outputs

Returns the removed preference object.

JavaScript API

UDF.removePreference(prefName, prefValue, optinDate, expirationDate, callback)

Events Triggered

• Generates L1 ObjectInsertOrUpdateEvent when updating preference record
• Generates L2 RemovePreferenceEvent when preference is removed from member

Possible Errors

Additional Considerations

• Preference is marked as cancelled in the preferences collection
• Member document is updated to remove the processed preference
• Events are generated before database updates
• Automatically sets update timestamp on the preference record

Begin Streak¶

This action starts a new streak instance for a member.

Parameters

The Opts object can contain:

{
  streakPolicyId: string,   // Optional. ID of the streak policy. Defaults to current rule's streakPolicyId
  startedAt: Date,         // Optional. When the streak starts. Defaults to activity date
  status: string,          // Optional. Initial status. Defaults to 'Active'
  value: number,          // Optional. Initial value. Defaults to 0
  errorOnExisting: boolean, // Optional. Whether to error if active streak exists. Defaults to false
  errorOnInstanceLimit: boolean, // Optional. Whether to error if instance limit exceeded. Defaults to false
  errorOnCoolOffTime: boolean,  // Optional. Whether to error if cool off time not met. Defaults to false
  goalValues: Array,      // Optional. Override policy goal values if memLevelOverride flag is true
  ctlGroup: any          // Optional. Control group value
}

JavaScript API

UDF.beginStreak(opts, callback)

Events Triggered

• Generates L2 StreakStartEvent when the streak is started

Possible Errors

Additional Considerations

• Validates that the streak policy exists and is configured correctly
• Checks the instance limits against policy settings
• Validates that the cool off time between streak instances
• Supports goal value overrides if the policy allows
• Emits instance limit and cool off skip events when those conditions occur

Cancel Streak¶

This action cancels an active streak instance and all its goals.

Parameters

The Opts object can contain:

{
  streakPolicyId: string,   // Optional. ID of the streak policy. Defaults to current rule's streakPolicyId
  date: Date               // Optional. Date of cancellation. Defaults to activity date
}

JavaScript API

UDF.cancelStreak(opts, callback)

Events Triggered

• Generates L2 StreakCancelEvent when streak is cancelled

Possible Errors

Additional Considerations

• Sets the streak status to 'Cancelled'
• Sets all active goals to 'Cancelled'
• Sets the cancellation date on the streak and all goals
• Only cancels streaks that are in 'Active' status

Evaluate Streak¶

This action evaluates active goals and the overall streak status.

Parameters

The Opts object can contain:

{
  streakPolicyId: string,   // Optional. ID of the streak policy. Defaults to current rule's streakPolicyId
  date: Date,              // Optional. Date of evaluation. Defaults to activity date
  postEndEval: boolean     // Optional. Indicates evaluation is running after end date. Defaults to false
}

JavaScript API

UDF.evalStreak(opts, callback)

Events Triggered

• Generates L2 StreakGoalExpirationEvent when a goal expires
• Generates L2 StreakGoalCompletionEvent when a goal completes
• Generates L2 StreakExpirationEvent when streak expires
• Generates L2 StreakCompletionEvent when streak completes

Possible Errors

Additional Considerations

• Evaluates completion and expiration of both goals and the overall streak
• Goals can expire based on time limits from streak start or goal start
• Streak completes when the required number of goals are completed
• Streak expires if too many goals expire to meet the completion requirements
• All goal statuses are evaluated before the streak status

Advance Streak Goal¶

This action advances a member's streak goal value when they perform a qualifying activity.

Parameters

The Opts object can contain:

{
  streakPolicyId: string,   // Optional. ID of the streak policy. Defaults to current rule's streakPolicyId
  goalName: string,         // Optional. Name of the goal to advance. Defaults to current rule's goalName
  date: Date,              // Optional. Date of the advancement. Defaults to activity date
  value: number,           // Optional. Value to add to goal. Defaults to 0
  consumeRemainder: boolean // Optional. Whether to consume remainder after reaching target. Defaults to false
}

JavaScript API

UDF.advanceGoal(opts, callback)

Events Triggered

• Generates L2 StreakGoalAdvanceEvent when goal value is advanced

Possible Errors

Additional Considerations

• Only advances the goal if member has an active streak
• Validates goal exists before advancing
• Only emits event if goal value actually changes
• If consumeRemainder is false, any value above the goal target is returned as remainder
• Goal value is rounded to streak policy's precision setting

Give Badge¶

This action adds a badge to a member.

Parameters

JavaScript API

UDF.addBadge(badgeName, callback)

Events Triggered

• Generates L2 AddBadgeEvent when badge is added

Possible Errors

| Error Code | Error Message | Description | |-|-|-|-| | 1524 | Please use unique badge name for field name | Reported if member already has a badge with the given name |

Additional Considerations

• Includes activity ID, rule ID, and timestamps in badge metadata
• Badge is added to member.badges array

Set Tier¶

The action sets a specific tier level for a member, with optional expiration and lock dates. This is both a rule action and a user-defined function (UDF).

Parameters

JavaScript API

UDF.setLevel(tierName, level, requalsOn, achievedOn, lockDate, reason, subReason, cb)

Outputs

• Updated tier object
• Sets context.Context.saveMember = true