Earn Rules

Overview

Earn Rules specify how Members earn metrics (such as reward points) for different Activity types. Earn Rules are typically used by clients who have an "earn and burn" style program, in which Members makes purchases in order to earn points. Members can then spend those points on Rewards, or to make other purchases.  

An Earn Rule comprises the following elements:

  • Activity Type: An action that a Member must take, such as a purchase.

  • Metric: The metric whose value is calculated by this Earn Rule.

  • Condition: If a condition is specified, the Earn Rule is applied only if the condition is true.

  • Calculation: The earned metric value from this Rule; note that this value may combine with the result of other Earn Rules for determining the final result.

  • Status: The life cycle status of the Earn Rule, including its effectivity period.

Calculations and Conditions can be written as Groovy expressions. You can use Calculation Functions to encapsulate common scenarios and to simplify the process of authoring Earn Rules. Further, custom encapsulation of Calculation or Condition scenarios can be written as Member Functions. Many rule calculations may be accomplished as a lookup from a spreadsheet of key/value pairs.

Examples

Below are several examples of common Earn Rules.

Description: For every point-of-sale Purchase, earn 1 Reward Point for each $1 spent.

  • Activity Type: PoS Purchase

  • Metric: Reward Points

  • Condition: Empty

  • Calculation:

getActivityValue('amount')

Description: Give a 15 Reward Point bonus for purchases more than $200.

  • Activity Types: PoS Purchase

  • Metric: Reward Points

  • Condition:

getActivityValue('amount') >= 200

  • Calculation: 15

Description: Give different Reward Points for items purchased. The Lookup table "point_lookup" defines how many points to give for every dollar spent for items in different categories. The result in the lookup is stored in the column "point_factor." The value in "point_factor" in the Lookup table needs to be multiplied by the amount spent on the item.

  • Activity Types: PoS Purchase

  • Metric: Reward Points

  • Condition: Empty

  • Calculation:

sumActivityItems({item -> getLookupValue ('point_lookup', item.category, 'point_factor') * item.amount})

Rule Groups

The platform allows you to assign Earn Rules to a Rule Group. Rule Groups serve as an organizational function, and also as tool to implement common loyalty scenarios. For more details on setting up Rule Groups, please see Earn Rule Settings.

Access

To access the Earn Rules screen, select Rules from the Main Navigation Menu, then select Earn Rules from the Sub-Category menu.

Features

The Earn Rules screen provides the following features:

Searching and Sorting

Search

The search feature allows you to search for a specified text string anywhere within the Earn Rule's Display Name or Internal Name.

  1. Optionally, in the search field near the top of Earn Rules screen, enter the desired text string.

  2. Optionally, from the "Status" drop-down menu, select an Earn Rule status (or "Any status").  

  3. Optionally, from the "Group" drop-down menu, select an Earn Rule Group (or "Any Group").  

  4. Optionally, from the "Activity Type" drop-down menu, select one or more Activity Types on which the Earn Rule is based (or "Any Activity Type").  

  5. Optionally, from the "Effectivity" drop-down menu, select an Earn Rule effectivity (or "Any effectivity").  

  6. Press Enter, or click the search button (magnifying glass icon).

  7. The Earn Rules screen is refreshed to show only the Earn Rules that meet your search criteria. Please note that if you enter multiple search criteria, the platform displays only the Earn Rules that meet ALL criteria.

  8. To remove all search criteria, click the remove button ("X" icon).

Expand / Collapse

Within the Earn Rules screen, all of the Earn Rules are displayed beneath a sub-heading that indicates the Earn Rule Group. Optionally, you can expand / collapse a Earn Rule Group by clicking the minus-sign or plus-sign icon next to the Earn Rule name.

Create a New Earn Rule

To create a new Earn Rule:

  1. In the "Enter Display Name" field, enter the Display Name value for the new Earn Rule.

  2. Click create to display the "Edit Calculation Rule" pop-up window.

  3. The "Display Name" field is populated with the value you entered above; optionally edit this value.

  4. The "Internal Name" is automatically populated based on the Display Name value. This field is disabled by default. To edit the Internal Name, check "Edit Internal Name."  A confirmation dialog box is displayed; click ok. Edit the Internal Name value.

  5. In the "Description" field, enter a description of the Earn Rule.

  6. From the "Rule Grouping" drop-down menu, select the Earn Rule Group to which this new Rule should be assigned (see Earn Rule Settings for more information on Earn Rule Groups).

  7. Click into the "Activity Type" field, and select an Activity Type from the drop-down menu. Repeat this step as needed to assign additional Activity Types to this Earn Rule.

  8. From the "Metric" drop-down menu, select the point metric that this Earn Rule will calculate.

  9. Click save.

Define the condition

When the Member performs the Activity specified for an Earn Rule, the platform checks the Condition, which is represented as a logical expression. The Earn Rule is invoked only if this Condition is satisfied.

Note: The use of Conditions is optional. If the Condition is not defined, the Earn Rule will apply to every individual who performs the assigned Activity Type.

To define the Earn Rule Condition

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Click the Edit icon within the Condition column to display the Conditions pop-up window.

  3. Click the Add button (plus-sign icon) and select "Add Rule."

  4. From the first drop-down menu, select the desired field.

  5. Select a mathematical operator.  

  6. Enter or select a value.

  7. Repeat the above steps as needed to define more Rules.

  8. Once you define more than one Rule, select the logical operator. From the "Include customers that meet" drop-down menu above the list of Rules, select either:

  • All of the following (i.e., an AND operator)

  • Some of the following (i.e., an OR operator)

  1. Optionally, to clear all Rules from this Condition, click remove condition.

  2. If you need to define additional Conditions for this Earn Rule, click add condition. Repeat the above steps to define the Rule, or Rules, for the Condition.

Note: Instead of defining a Rule through the user interface, you can provide code to perform more complex query logic. Enter your custom code in the Advanced Expression field.

  1. Click save.

When defining the Rules for the Condition, you can optionally organize the Rules into a Group to create more sophisticated logical statements.

  1. Within the Conditions pop-up window, click the Add button (plus-sign icon) and select "Add Rule Group."

  2. Follow the steps described above to define the Rule, or Rules, within the Group, as well as the Group's logical operator.

  3. If you need to delete a Group (and all Rules within it), click the Delete icon within the Group.  

  4. Click save.

Define the calculation

The Calculation specifies the mathematical formula for the point metric. If the Condition is met, the platform calculates the appropriate adjustment to the Member's earned point value.

Note: Defining the Calculation requires knowledge of the Groovy programming language.  

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Click the Edit icon within the Calculation column to display the "Calculation Rule" pop-up window.

  3.  Next to Authoring Mode, select "Expression."

Note: This Help topic doesn't cover the Template authoring mode.

  1. In the Expression field, enter the Groovy expression.

  2. Optionally, click validate expression to validate the Groovy code. A message is displayed, indicating the results of the validation.

  3. Click save.

Set Status and Effectivity Period

To edit the status and Effectivity Period for an Earn Rule:

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Click the Edit icon within the Status column to display the Calculation Rule pop-up window.  

  3. From the "Status" drop-down menu, select the Earn Rule status.

  4. Make any necessary changes to the Earn Rule's overall effectivity. Valid values are:

  • Always: This Earn Rule doesn't expire.

  • Schedule: Enter a start date and end date. Optionally, check "Recurring" to use a recurring schedule. Select the desired schedule from the "Recurring Schedule" drop-down menu, or define a new recurring schedule (see below for details on that process).

  1. Click save.  

Define a new recurring schedule

To define a new recurring schedule for an Earn Rule's effectivity:

  1. From the "Recurring Schedule" drop-down menu, select "Enter Schedule." The "Repeat" pop-up window is displayed.

  2. From the "Frequency" drop-down menu, select a recurrence frequency -- Weekly or Monthly.

  3. In the text field, enter the interval.

  4. For a Weekly frequency, select one or more days of the week. For example, "Tuesdays and Thursdays."

  5. For a Monthly frequency, choose one of the following options:

  • Day of month: Select one or more days of the month. For example, "the 15th and the 30th."

  • Day of week: Select one or more days of the week, for each of the four weeks within a month. For example: "the second Wednesday of the month."

  1. Click ok. The system adds the new schedule to the "Recurring Schedule" drop-down menu.

Deploy Earn Rules Metadata

After you've created an Earn Rule, you must deploy the Earn Rule metadata. When you deploy the Earn Rules metadata to the server, the process automatically deploys the metadata for ALL modified Earn Rules.

  1. From the "Actions" menu in the top-right corner, select "Validate Earn Rules Metadata."

Note: You can deploy metadata immediately, but the best practice is to validate the Earn Rules logic before deploying metadata to ensure no incorrect expression code gets deployed to the server that could cause issues.

  1. If the validation step passes, you'll see a message that says, "Earn Rules metadata is valid." If the validation step fails, you'll receive an error message; review and correct your Earn Rules expressions, then retry the validation step.

  2. Click deploy earn rules metadata.

  3. If the deployment was successful, you'll see a message that says, "Earn Rules metadata as been deployed."

View Deployed Earn Rules Metadata

To see the details of what Earn Rules metadata has been deployed:

  1. From the "Actions" menu in the top-right corner of the screen, select "View Deployed Earn Rules." The "View Snapshot" pop-up window is displayed.

  2. Click the plus-sign to expand the message to view additional details, such as the total number of deployed Earn Rules. You can also drill in deeper, to see details of each deployed Earn Rules (Earn Rule name, type, conditions, etc.).

  3. When finished, click the "X" icon to close the pop-up window.

Rearrange Earn Rules

The sequence in which the Earn Rules appear within an Earn Rule Group controls the sequence in which the platform executes the Earn Rules in that Group. For example, if you have five Earn Rules within a Group, and that Group is configured to use the "Execute only first applicable rule" strategy, the platform will interrogate the first Earn Rule in the Group. If that condition fails, the platform will move on to the second Earn Rule, and so forth.

To rearrange the Earn Rules:

  1. To the left of the desired Earn Rule, click and hold on the "handle" area.

  2. Drag-and-drop the Earn Rule to its desired new sequence.

Note: You can't drag-and-drop an Earn Rule into a different Earn Rule Group. To change an Earn Rule's inclusion in a Group, you must edit its properties (see below for more details on this process).

Edit Earn Rule Properties

To edit the properties of an Earn Rule:

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Within the appropriate column ("Calculation Rule," "Condition," "Calculation," or "Status" ) of the desired Earn Rule, click the edit icon. The corresponding pop-up window is displayed.

  3. Make any necessary changes to the Earn Rule properties.

  4. Click save.  

Delete an Earn Rule

To delete an Earn Rule:

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Within the right-most column of the desired Earn Rule, click the Delete icon. A confirmation dialog box is displayed.

  3. Click confirm.

Copy an Earn Rule

The Loyalty platform allows you to copy an Earn Rule to use as the basis for a new Earn Rule. To copy an Earn Rule:

  1. Find the desired Earn Rule on the Earn Rules screen.

  2. Within the right-most column of the desired Earn Rule, click the Copy icon. The system creates a new Earn Rule. The default name of the new Earn Rule is the name of the original Earn Rule, followed by a counter, such as "(1)."  

Download JSON

To download the underlying JSON code for all Earn Rules:

  1. From the "Actions" menu in the top-right corner of the screen, select either "Download JSON" or "Download JSON (Batch)."

  2. The JSON code for all Earn Rules in your account is displayed in a separate browser tab.