Projects:Loyalty Programs/Technical Documentation
Introduction
This technical document has been split in two parts.
The main objective of the first part, Core Module - Loyalty Programs, is to describe the required tables, windows and processes to implement the base infrastructure of Loyalty Programs in a standard Openbravo instance.
The main objective of the second part, Retail Module - Loyalty Programs for Web POS, is to extend and complement the definition of the first part and describe the necessary artifacts to implement the subscription to loyalty programs from Web POS.
Core Module - Loyalty Programs
- Name: Loyalty Programs
- Repository: https://code.openbravo.com/erp/pmods/org.openbravo.loyalty.programs
- Java Package: org.openbravo.loyalty.programs
- DB prefix: OBLP
New Database Objects
New table OBLP_PROGRAM
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_program_id | varchar(32) | ID of the table | Y | |
value | varchar(60) | Search Key of the Loyalty Program | Y | |
name | varchar(255) | Name of the Loyalty Program | Y | |
description | varchar(2000) | Description of the Loyalty Program | N | |
datefrom | timestamp | Date after which the Loyalty Program is valid | Y | |
dateto | timestamp | Date until which the Loyalty Program is valid | N | |
isexclusive | char(1) | Flag to define if this program can be combined with other programs | Y | N |
ad_sequence_id | varchar(32) | Foreign Key to ad_sequence. Defines the sequence to generate subscription IDs | Y |
Application Dictionary Definition:
- Name: OBLP_Program
- Data Origin: Table
- DB Table Name: OBLP_Program
- Java Class Name: OBLPProgram
- Data Access Level: Client/Organization
- Window: Loyalty Programs (see below)
New table OBLP_STATUS
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_status_id | varchar(32) | ID of the table | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program. Oblp_status will be a child table of oblp_program | Y | |
name | varchar(60) | Name of the Subscription Status | Y | |
sequence | numeric | Defines a logical order between different statuses | Y | |
isdefault | char(1) | Flag to define if the status is the default status | Y | N |
canearnpoints | char(1) | Flag to define if subscriptions in this status can earn points | Y | Y |
Application Dictionary Definition:
- Name: OBLP_Status
- Data Origin: Table
- DB Table Name: OBLP_Status
- Java Class Name: OBLPStatus
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_RULE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_rule_id | varchar(32) | ID of the table | Y | |
ad_module_id | varchar(32) | Foreign Key to ad_module | Y | |
value | varchar(40) | Search Key of the Rule | Y | |
name | varchar(255) | Name of the Rule | Y | |
description | varchar(2000) | Description of the Rule | N | |
type | varchar(60) | Type of the Rule (Earn/Burn/Promotion) | Y | |
canbeexecutedmanually | char(1) | Flag to indicate if the rule can be used in the manual Burn process | Y | Y |
canbeexecutedbg | char(1) | Flag to indicate if the rule can be used in the background process to burn points | Y | Y |
Application Dictionary Definition:
- Name: OBLP_Rule
- Data Origin: Table
- DB Table Name: OBLP_Rule
- Java Class Name: OBLPRule
- Data Access Level: System only
- Window: Earn Rule
New table OBLP_CONVERSION
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_conversion_id | varchar(32) | ID of the table | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program. Oblp_status will be a child table of oblp_program | Y | |
c_currency_id | varchar(32) | Currency user to burn points | Y | |
datefrom | timestamp | Date after which the points-to-currency conversion is valid | Y | |
price | numeric | Price of each point in the given currency | Y | 1 |
Application Dictionary Definition:
- Name: OBLP_Conversion
- Data Origin: Table
- DB Table Name: OBLP_Conversion
- Java Class Name: OBLPConversion
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_CATEGORY
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_category_id | varchar(32) | ID of the table | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program. Oblp_category will be a child table of oblp_program | Y | |
name | varchar(255) | Name of the Program Category | Y | |
isdefault | char(1) | Flag to define if this is the default category | Y | N |
level | numeric | Defines the hierarchy between different categories | Y |
Application Dictionary Definition:
- Name: OBLP_Category
- Data Origin: Table
- DB Table Name: OBLP_Category
- Java Class Name: OBLPCategory
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_EARN_RULE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_earn_rule_id | varchar(32) | ID of the table | Y | |
oblp_category_id | varchar(32) | Foreign Key to oblp_category. Oblp_earn_rule will be a child table of oblp_category | Y | |
name | varchar(255) | Name of the Rule | Y | |
oblp_rule_id | varchar(32) | Foreign Key to oblp_rule | Y | |
oblp_burn_rule_id | varchar(32) | Foreign Key to oblp_program_burn_rule. Can be used to define a specific Burn rule for points earned using this rule. | N | |
datefrom | timestamp | Date after which the rule is valid | Y | |
dateto | timestamp | Date until which the rule is valid | N | |
org_selection | varchar(60) | Include or Exclude selected organizations | Y | EXCL |
Application Dictionary Definition:
- Name: OBLP_Earn_Rule
- Data Origin: Table
- DB Table Name: OBLP_Earn_Rule
- Java Class Name: OBLPEarnRule
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_EARN_RULE_ORG
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_earn_rule_org_id | varchar(32) | ID of the table | Y | |
oblp_earn_rule_id | varchar(32) | Foreign Key to oblp_earn_rule. Oblp_earn_rule_org will be a child table of oblp_earn_rule | Y | |
ad_org_id | varchar(32) | Foreign Key to ad_org. Represents the organization that needs to be included/excluded | Y |
Application Dictionary Definition:
- Name: OBLP_Earn_Rule_Org
- Data Origin: Table
- DB Table Name: OBLP_Earn_Rule_Org
- Java Class Name: OBLPEarnRuleOrg
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_CATEGORY_RULE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_category_rule_id | varchar(32) | ID of the table | Y | |
oblp_category_id | varchar(32) | Foreign Key to oblp_category. Oblp_category_rule will be a child table of oblp_category | Y | |
name | varchar(255) | Name of the Rule | Y | |
oblp_rule_id | varchar(32) | Foreign Key to oblp_rule | Y | |
datefrom | timestamp | Date after which the rule is valid | Y | |
dateto | timestamp | Date until which the rule is valid | N |
Application Dictionary Definition:
- Name: OBLP_Category_Rule
- Data Origin: Table
- DB Table Name: OBLP_Category_Rule
- Java Class Name: OBLPCategoryRule
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_PROGRAM_BURN_RULE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_program_burn_rule_id | varchar(32) | ID of the table | Y | |
name | varchar(255) | Name of the rule | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program. Oblp_program_burn_rule will be a child table of oblp_program | Y | |
oblp_rule_id | varchar(32) | Foreign Key to oblp_rule | Y | |
datefrom | timestamp | Date after which the rule is valid | Y | |
dateto | timestamp | Date until which the rule is valid | N | |
canbeexecutedmanually | char(1) | Flag to indicate if the rule can be used in the manual Burn process | Y | N |
canbeexecutedbg | char(1) | Flag to indicate if the rule can be used in the background process to burn points | Y | Y |
org_selection | varchar(60) | Include or Exclude selected organizations | Y | EXCL |
Application Dictionary Definition:
- Name: OBLP_Program_Burn_Rule
- Data Origin: Table
- DB Table Name: OBLP_Program_Burn_Rule
- Java Class Name: OBLPProgramBurnRule
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_BURN_RULE_ORG
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burn_rule_org_id | varchar(32) | ID of the table | Y | |
oblp_program_burn_rule_id | varchar(32) | Foreign Key to oblp_program_burn_rule. Oblp_burn_rule_org will be a child table of oblp_program_burn_rule | Y | |
ad_org_id | varchar(32) | Foreign Key to ad_org. Represents the organization that needs to be included/excluded | Y |
Application Dictionary Definition:
- Name: OBLP_Burn_Rule_Org
- Data Origin: Table
- DB Table Name: OBLP_Burn_Rule_Org
- Java Class Name: OBLPBurnRuleOrg
- Data Access Level: Client/Organization
- Window: Loyalty Programs
New table OBLP_SUBSCRIPTION
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_subscription_id | varchar(32) | ID of the table | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program | Y | |
oblp_category_id | varchar(32) | Foreign Key to oblp_category | Y | |
memberid | varchar(60) | Unique, sequence based identifier for each subscription of a specific program. | Y | |
startingdate | timestamp | Date of the subscription | Y | |
c_bpartner_id | varchar(32) | Foreign Key to c_bpartner. Represents the customer who subscribed to the Loyalty Program | Y | |
c_currency_id | varchar(32) | Foreign Key to c_currency. Represents the Currency used by the subscribed Customer | Y | |
totalpoints | numeric | Amount of the currently available points | Y | 0 |
oblp_status_id | varchar(32) | Foreign Key to oblp_status. Represents the current status of the subscription | Y | |
description | varchar(2000) | Additional description | N | |
changestatus | char(1) | Field to enable the Change Status Process Button | Y |
Application Dictionary Definition:
- Name: OBLP_Subscription
- Data Origin: Table
- DB Table Name: OBLP_Subscription
- Java Class Name: OBLPSubscription
- Data Access Level: Client/Organization
- Window: Subscriptions (see below)
New table OBLP_SUBSCRIPTION_LOG
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_subscription_log_id | varchar(32) | ID of the table | Y | |
oblp_subscription_id | varchar(32) | Foreign Key to oblp_subscription. | Y | |
initialstatus | varchar(32) | Foreign Key to oblp_status. Represents the initial status of the subscription when the subscription log was registered. | Y | |
finalstatus | varchar(32) | Foreign Key to oblp_status. Represents the final status of the subscription when the subscription log was registered. | Y | |
result | char(1) | Yes/No value indicating if the subscription change represented by this log was processed correctly | Y | Y |
date | timestamp | Date representing when this subscription log was registered | Y | |
description | varchar(2000) | Additional description for this subscription log | N |
Application Dictionary Definition:
- Name: OBLP_Subscription_Log
- Data Origin: Table
- DB Table Name: OBLP_Subscription_Log
- Java Class Name: OBLPSubscriptionLog
- Data Access Level: Client/Organization
- Window: Subscription
New table OBLP_CARD
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_card_id | varchar(32) | ID of the table | Y | |
oblp_subscription_id | varchar(32) | Foreign Key to oblp_subscription | Y | |
Issuedate | timestamp | Date representing when the card was issued | Y | |
expirationdate | timestamp | Expiration date of the card | Y | |
cardnumber | varchar(60) | Identifier of the card | Y |
Application Dictionary Definition:
- Name: OBLP_Card
- Data Origin: Table
- DB Table Name: OBLP_Card
- Java Class Name: OBLPCard
- Data Access Level: Client/Organization
- Window: Subscriptions
New table OBLP_EARNED_POINTS
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_earned_points_id | varchar(32) | ID of the table | Y | |
date | timestamp | Date representing when the points were earned | Y | |
oblp_subscription_id | varchar(32) | Foreign Key to oblp_subscription | Y | |
event | varchar(255) | Short text explaining the earning rule applied | Y | |
log | varchar(2000) | Full text explaining the steps followed to calculate the earned points | N | |
oblp_earn_rule_id | varchar(32) | Foreign Key to oblp_earn_rule | Y | |
totalpoints | numeric | Total amount of points earned in this transaction | Y | 0 |
availablepoints | numeric | Available (not yet burned) points in this transaction | Y | 0 |
ismanual | char(1) | Indicates if this transaction was added manually | Y | N |
oblp_card_id | varchar(32) | Foreign Key to oblp_card. Indicates the card associated with this transaction | N | |
manualburn | char(1) | Field to enable the Manual Burn Process Button | Y |
Application Dictionary Definition:
- Name: OBLP_Earned_Points
- Data Origin: Table
- DB Table Name: OBLP_Earned_Points
- Java Class Name: OBLPEarnedPoints
- Data Access Level: Client/Organization
- Window: Subscriptions
- Deletable records: false.
New table OBLP_BURNED_POINTS
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burned_points_id | varchar(32) | ID of the table | Y | |
date | timestamp | Date representing when the points were earned | Y | |
oblp_subscription_id | varchar(32) | Foreign Key to oblp_subscription | Y | |
event | varchar(255) | Short text explaining the burning rule applied | Y | |
log | varchar(2000) | Full text explaining the steps followed to calculate the burning output | N | |
oblp_program_burn_rule_id | varchar(32) | Foreign Key to oblp_program_burn_rule | Y | |
totalpoints | numeric | Total amount of points burned in this transaction | Y | 0 |
oblp_burn_run_rule_id | varchar(32) | Foreign Key to oblp_burn_run_rule | N |
Application Dictionary Definition:
- Name: OBLP_Burned_Points
- Data Origin: Table
- DB Table Name: OBLP_Burned_Points
- Java Class Name: OBLPBurnedPoints
- Data Access Level: Client/Organization
- Window: Subscriptions
New table OBLP_POINTS_DETAIL
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_points_detail_id | varchar(32) | ID of the table | Y | |
oblp_earned_points_id | varchar(32) | Foreign Key to oblp_earned_points | Y | |
oblp_burned_points_id | varchar(32) | Foreign Key to oblp_burned_points | Y | |
points | numeric | Amount of points burned from the earn transaction | Y | 0 |
Application Dictionary Definition:
- Name: OBLP_Points_Detail
- Data Origin: Table
- DB Table Name: OBLP_Points_Detail
- Java Class Name: OBLPPointsDetail
- Data Access Level: Client/Organization
- Window: Subscriptions
New table OBLP_BURN_RUN
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burn_run_id | varchar(32) | ID of the table | Y | |
name | varchar(255) | Descriptive name of the Burn Run | Y | |
oblp_program_id | varchar(32) | Foreign Key to oblp_program | Y | |
burn_run_date | timestamp | Expected date of execution of the Burn Run | Y | |
date_limit | timestamp | Date until which earning transactions (points earned) will be considered for burning | N | |
copy | char(1) | Flag enabling a Copy Configuration button | Y | |
setasready | varchar(60) | Field enabling a Set as Ready button with dynamic text | Y | RD |
status | varchar(60) | Current status of the Burn Run (draft / pending / executed / error) | Y | DR |
simulate | char(1) | Char field required to create the Process Button | Y | N |
Application Dictionary Definition:
- Name: OBLP_Burn_Run
- Data Origin: Table
- DB Table Name: OBLP_Burn_Run
- Java Class Name: OBLPBurnRun
- Data Access Level: Client/Organization
- Window: Burn Run (see below)
New table OBLP_BURN_RUN_RULE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burn_run_rule_id | varchar(32) | ID of the table | Y | |
oblp_burn_run_id | varchar(32) | Foreign Key to oblp_burn_run | Y | |
priority | numeric | Defines the evaluation priority between different rules | Y | |
oblp_program_burn_rule_id | varchar(32) | Foreign Key to oblp_program_burn_rule | Y | |
log | varchar(2000) | Full text explaining the output of the Burn Run Rule after its execution | N |
Application Dictionary Definition:
- Name: OBLP_Burn_Run_Rule
- Data Origin: Table
- DB Table Name: OBLP_Burn_Run_Rule
- Java Class Name: OBLPBurnRunRule
- Data Access Level: Client/Organization
- Window: Burn Run
New table OBLP_BURN_RUN_SIM
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burn_run_sim_id | varchar(32) | ID of the table | Y | |
oblp_burn_run_id | varchar(32) | Foreign Key to OBLP_Burn_Run. Reference to the Burn Run that is being simulated | Y | |
oblp_subscription_id | varchar(32) | Foreign Key to OBLP_Subscription. Subscription for which the points would be burned | Y | |
burnedpoints | numeric | Points Burned in this specific transaction | Y |
Application Dictionary Definition:
- Name: OBLP_Burn_Run_Sim
- Data Origin: Table
- DB Table Name: OBLP_Burn_Run_Sim
- Java Class Name: OBLPBurnRunSim
- Data Access Level: Client/Organization
- Window: Burn Run
New table OBLP_BURN_RUN_SIM_TRX
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
oblp_burn_run_sim_trx_id | varchar(32) | ID of the table | Y | |
oblp_burn_run_sim_id | varchar(32) | Foreign Key to OBLP_Burn_Run_Sim. Represents which simulated burn transaction these points would belong to. | Y | |
oblp_earned_points_id | varchar(32) | Foreign Key to OBLP_Earned_Points. Represents the origin of points that would be burned on the related simulated transaction. | Y | |
totalpoints | numeric | Original amount of points of the Earned Points transaction | Y | |
availablepoints | numeric | Available points of the Earned Points transaction at the time of the simulation | Y |
Application Dictionary Definition:
- Name: OBLP_Burn_Run_Sim_Trx
- Data Origin: Table
- DB Table Name: OBLP_Burn_Run_Sim_Trx
- Java Class Name: OBLPBurnRunSimTrx
- Data Access Level: Client/Organization
- Window: Burn Run
Application Dictionary Definition
The following new AD objects have been added:
New List References
- OBLP Burn Run actions: List of actions available in the Burn Run window
- RD - Set as Ready
- CN - Cancel
- Loyalty Rule Type
- BURN - Burn
- CAT - Category
- EARN - Earn
- Inclusion/Exclusion: Convenience list to be used in configuration tabs
- EXCL - All Excluding Defined
- INCL - Only Those defined
- Burn Run Status
- DR - Draft
- ER - Error
- PE - Pending
- RU - Running
- EX - Executed
New Processes
Burn Run Process
- Type: Report and Process
- Background: 'Y'
This background process will be executed periodically and will consume Burn Run configurations which are in Pending status, when the execution date arrives.
For each Burn Run, it will execute the rules in the priority order. Each of these rules will have a java class behind, extending this class: BurnRunProcess.
The BurnRunProcess class will be located in the org.openbravo.loyalty.programs.process package.
This class will require that its extending classes define the method exec that receives as a parameter the Burn Run Rule id. The class will also require to define a writeLog method to save the execution log of the rule into the Burn Run.
After all the Burn Run Rules have been executed, the process will change the status of the Burn Run to Executed or Error, and will change the internal value of the setasready field to CN.
The logic that executes the rules of a single burn run record will be located in a separate Utils class (BurnRunUtils.java, located on the org.openbravo.loyalty.programs.utils package), in a static method named processBurnRun.
This processBurnRun method will receive the following parameters:
- The Burn Run being executed
- The ProcessLogger instance (if available)
- A boolean indicating if the execution is a simulation or not (isSimulation)
- A Map<String, Object> of simulationParameters.
Change Status
- Type: Process Definition, Standard
- Input Parameters: New Status
- Multirecord: 'Y'
This process changes the status of a Program Subscription between the available statuses of the Loyalty Program.
It will be available in the Subscription tabs (either directly in the Subscriptions window, in the Business Partner || Subscriptions tab or in the Loyalty Program || Subscriptions tab).
Copy Burn Run Configuration
- Type: Process Definition, Standard
- Input Parameters: none
- Multirecord: 'N'
This process allows to copy the Burn Run configuration (including specific configurations for each rule) and create a new Burn Run. This process will be available in the Burn Run window.
This process will expose a hook so external modules (which might be owners of different Rule Types) can implement custom logic to copy each of the rule configurations.
The fields Ready and Status will be reset to default so the new Burn Run can be further adjusted before being used.
- Hook Definition
- Class name: CopyBurnRunConfigurationHook
- Package: org.openbravo.loyalty.programs.process
- The hook will be an abstract class, and will implement a single method:
- public void exec(OBLPBurnRun baseBurnRun, OBLPBurnRun newBurnRun) throws Exception;
- The hook will be called after the new burn run (and its rules) have been created, so implementations of the hook will be able to work on both the header of the new Burn Run and its rules.
Manual Burn
- Type: Process Definition, Standard
- Input Parameters: Burn Rule. The list of available Burn Rules will be filtered using the 'Can Be Executed Manually' criteria.
- Multirecord: 'Y'
This process takes several Earned Points lines and tries to apply a burn rule (selected as a parameter) to them to consume them. This process will be available in all Earned Points tabs (in Subscriptions || Earned Points, in the Business Partner || Subscriptions || Earned Points tab or in the Loyalty Program || Subscriptions || Earned points tab).
Each Burn Rule will have a java class behind, extending the class: ManualBurnProcess. This class will require that its extending classes define the method exec that receives as parameters a collection of Earned Points and the Burn Rule Definition for the Loyalty Program (oblp_program_burn_rule_id).
Set As Ready
- Type: Process Definition, Standard
- Input Parameters: none
- Multirecord: 'Y'
This process marks a Burn Run as Ready, making it available for the Burning Points Background Process.
This process will be available in the Burn Run window. If the Burn Run was already Set as Ready, and it hasn’t been executed yet, the process will Reactivate the Burn Run and mark it again as “not ready”.
Simulate Burn Run
- Type: Process Definition, Standard
- Input Parameters: none
- Multirecord: 'N'
This process will call the processBurnRun method in BurnRunUtils with the isSimulation parameter passed as True. The Burn Rules defined for the current Burn Run will be iterated and its output will be simulated into the OBLP_Burn_Run_Sim and OBLP_Burn_Run_Sim_Trx tables.
Executing the simulation process will remove the simulation records of the Burn Run (if they exist) and create the new simulation records. Existing simulated transactions of other Burn Runs will remain intact.
New Auxiliary Inputs
- OBLP_RULETYPE
- Tab: Category Rule Type - Category Rule Type
- Code: "CAT"
- OBLP_RULETYPE
- Tab: Earn Rule Type - Earn Rule Type
- Code: "EARN"
- OBLP_RULETYPE
- Tab: Burn Rule Type - Burn Rule Type
- Code: "BURN"
- OBLP_RULETYPEEXECUTEDBG
- Tab: Burn Rules - Loyalty Program
- Code: @SQL=SELECT canbeexecutedbg FROM oblp_rule WHERE oblp_rule.oblp_rule_id = @Oblp_Rule_ID@
- OBLP_RULETYPEEXECUTEDMANUALLY
- Tab: Burn Rules - Loyalty Program
- Code: @SQL=SELECT canbeexecutedmanually FROM oblp_rule WHERE oblp_rule.oblp_rule_id = @Oblp_Rule_ID@
New Callouts
- Currency Of Store
Used to set the Currency of a Subscription when it is created. The currency is taken from the Organization the subscription belongs to.
- EarnedPoints Total Points
Used to initialize the availablePoints field of the Earned Points records to the value of totalPoints.
- Organization Of Program
Used to set the organization of a subscription, based on the organization of the its program.
- Subscription MemberID
Used to define a default <member ID> for a subscription, based on the member identifier sequence of the selected program.
- Type Of Rule
Used to default the Can Be Executed Manually and Can Be Executed In Background fields in Program Burn Rules, based on the definition of the selected rule type.
New Validations
- Can be executed BG of program
- Used to filter the Background Executable Burn Rules of a given Loyalty Program when configuring a list of rules for a Burn Run
- Card of Subscription
- Used to filter the available cards in the Earned Points definition
- Earn Rule of program
- Used to filter the available Earn Rules of a program when defining Earned Points
- For the loyalty program
- Used to filter elements (such as categories or statuses) belonging to a specific program when defining subscriptions.
- Rule type = EARN/BURN/CAT
- Three validations used to filter rule types in each on their corresponding configuration tabs under the definition of a Loyalty Program
Windows, Tabs and Fields
New Window: Earn Rule Type
Tab: Header
- Source table: OBLP_Rule
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Module
- Search Key
- Name
- Active
- Description
- SQL Where Clause: OBLP_Rule.type = ‘EARN’
- HQL Where Clause: e.type = ‘EARN’
New Window: Burn Rule Type
Tab: Header
- Source table: OBLP_Rule
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Module
- Search Key
- Name
- Active
- Description
- Can Be Executed manually
- Can Be Executed In Scheduled Process
- SQL Where Clause: OBLP_Rule.type = ‘BURN’
- HQL Where Clause: e.type = ‘BURN’
New Window: Category Rule Type
Tab: Header
- Source table: OBLP_Rule
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Module
- Search Key
- Name
- Active
- Description
- SQL Where Clause: OBLP_Rule.type = ‘CAT’
- HQL Where Clause: e.type = ‘CAT’
New Window: Loyalty Program
Tab: Header
- Source table: OBLP_Program
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Organization
- Search Key
- Name
- Active
- Exclusive
- Start Date
- End Date
- Description
- Member Identifier Sequence
Tab: Category
- Source table: OBLP_Category
- Level: 1
- Sequence Number: 20
- UI Pattern: Standard
- Fields
- Name
- Default
- Level
- Active
- Order by clause: order by level.
Tab: Earning Rules
- Source table: OBLP_Earn_Rule
- Level: 2
- Sequence Number: 30
- UI Pattern: Standard
- Fields
- Type of Earn Rule
- Name
- Active
- Start Date
- End Date
- Included Organizations
- Burn Rule
Tab: Organizations
- Source table: OBLP_Earn_Rule_Org
- Level: 3
- Sequence Number: 40
- UI Pattern: Standard
- Fields
- Organization
Tab: Category Rules
- Source table: OBLP_Category_Rule
- Level: 2
- Sequence Number: 50
- UI Pattern: Standard
- Fields
- Type of Category Rule
- Name
- Active
- Start Date
- End Date
Tab: Burn Rules
- Source table: OBLP_Program_Burn_Rule
- Level: 1
- Sequence Number: 60
- UI Pattern: Standard
- Fields
- Type of Burn Rule
- Name
- Active
- Start Date
- End Date
- Can Be Executed Manually
- Read Only logic: Type of Burn Rule -> Can Be Executed Manually = ‘N’
- Can Be Executed In Scheduled Process
- Read Only logic: Type of Burn Rule -> Can Be Executed In Scheduled Process = ‘N’
- Included Organizations
Tab: Organizations
- Source table: OBLP_Burn_Rule_Org
- Level: 2
- Sequence Number: 70
- UI Pattern: Standard
- Fields
- Organization
Tab: Conversions
- Source table: OBLP_Conversion
- Level: 1
- Sequence Number: 80
- UI Pattern: Standard
- Fields
- Currency
- Active
- Start Date
- Price of Point
Tab: Subscriptions
- Source table: OBLP_Subscription
- Level: 1
- Sequence Number: 90
- UI Pattern: Standard
- Fields
- Category
- Active
- Customer
- Date and Time of Subscription
- Member ID
- Store
- Currency
- Total Available Points
- Status
- Description
- Process Buttons:
- Change Status
Tab: Cards
- Source table: OBLP_Card
- Level: 2
- Sequence Number: 100
- UI Pattern: Standard
- Fields
- Issue Date
- Expiration Date
- Card Number
- Active
Tab: Earned Points
- Source table: OBLP_Earned_Points
- Level: 2
- Sequence Number: 110
- UI Pattern: Standard
- Fields
- Earn Rule
- Active
- Date and Time of Earn
- Earned Points
- Available Points
- Card
- Event
- Log
- Manual
- Process Buttons:
- Manual Burn
- Filter Clause: Available Points > 0
Tab: Burning of Points
- Source table: OBLP_Points_Detail
- Level: 3
- Sequence Number: 120
- UI Pattern: Read Only
- Fields
- Burned Point
- Date and Time of Burn
- Burning
Tab: Burned Points
- Source table: OBLP_Burned_Points
- Level: 2
- Sequence Number: 130
- UI Pattern: Standard
- Fields
- Burn Rule
- Active
- Date and Time of Burn
- Burned Points
- Event
- Log
Tab: Origin of Points
- Source table: OBLP_Points_Detail
- Level: 3
- Sequence Number: 140
- UI Pattern: Read Only
- Fields
- Points
- Origin
Tab: Subscription Log
- Source table: OBLP_Subscription_Log
- Level: 2
- Sequence Number: 150
- UI Pattern: Read Only
- Fields
- Initial Status
- Final Status
- Finished OK
- Date and Time
- Description
Tab: Status
- Source table: OBLP_Status
- Level: 1
- Sequence Number: 150
- UI Pattern: Standard
- Fields
- Default
- Name
- Sequence
- Can Earn Points
- Can Burn Points
- Order by clause: order by sequence.
New Window: Burn Run
Tab: Header
- Source table: OBLP_Burn_Run
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Name
- Loyalty Program
- Burn Date and Time
- Burn Execution Limit
- Status
- Process Buttons
- Set As Ready
- If the Burn Run is in status Draft, the button will be visible with the text Set As Ready
- If the Burn Run is in status Pending or Error, the button will be visible with the text Cancel
- If the Burn Run is in status Executed or Running, the button will not be visible
- Copy Configuration
- Simulate Burn Run
- Only visible when the Burn Run is in status Draft
- Set As Ready
- Read Only Logic:
- If the Burn Run has been set as Ready, all visible fields will be read only.
- Additionally, it will not be possible to insert/update/delete records from the child tabs (see triggers below).
Tab: Burn Rules
- Source table: OBLP_Burn_Run_Rule
- Level: 1
- Sequence Number: 20
- UI Pattern: Standard
- Fields
- Priority
- Burn Rule
- Log
- Read Only Logic:
- If the Burn Run has been marked as Ready, all visible fields will be read only.
Tab: Burned Points
- Source table: OBLP_Burned_Points
- Level: 2
- Sequence Number: 30
- UI Pattern: Read Only
- Fields
- Date and Time of Burn
- Burned Points
- Event
- Log
Tab: Simulation
- Source table: OBLP_Burn_Run_Sim
- Level: 1
- Sequence Number: 50
- UI Pattern: Read Only
- Fields
- Subscription
- Business Partner Name (Property field)
- Burned Points
Tab: Burned Transactions
- Source table: OBLP_Burn_Run_Sim_Trx
- Level: 2
- Sequence Number: 60
- UI Pattern: Read Only
- Fields
- Earn Rule (Property Field)
- Earn Date (Property Field)
- Total Points
- Available Points
- Log (Property Field)
New Window: Subscriptions
Tab: Header
- Source table: OBLP_Subscription
- Level: 0
- Sequence Number: 10
- UI Pattern: Standard
- Fields
- Category
- Active
- Customer
- Date and Time of Subscription
- Member ID
- Store
- Currency
- Total Available Points
- Status
- Description
- Process Buttons
- Change Status
Tab: Cards
- Source table: OBLP_Card
- Level: 1
- Sequence Number: 20
- UI Pattern: Standard
- Fields
- Issue Date
- Expiration Date
- Card Number
- Active
Tab: Earned Points
- Source table: OBLP_Earned_Points
- Level: 1
- Sequence Number: 30
- UI Pattern: Standard
- Fields
- Earn Rule
- Date and Time of Earn
- Earned Points
- Available Points
- Card
- Event
- Log
- Manual
- Process Buttons
- Manual Burn
Tab: Burning of Points
- Source table: OBLP_Points_Detail
- Level: 2
- Sequence Number: 40
- UI Pattern: Standard
- Fields
- Burned Points
- Date and Time of Burn
- Burning
Tab: Burned Points
- Source table: OBLP_Burned_Points
- Level: 1
- Sequence Number: 50
- UI Pattern: Standard
- Fields
- Burn Rule
- Active
- Date and Time of Burn
- Burned Points
- Event
- Log
Tab: Origin of Points
- Source table: OBLP_Points_Detail
- Level: 2
- Sequence Number: 60
- UI Pattern: Read Only
- Fields
- Points
- Origin
Tab: Subscription Log
- Source table: OBLP_Subscription_Log
- Level: 1
- Sequence Number: 70
- UI Pattern: Read Only
- Fields
- Initial Status
- Final Status
- Finished OK
- Date and Time
- Description
New Window: Earn + Burn Transactions
Tab: Header
- Source table: OBLP_Earned_Points
- Level: 0
- Sequence Number: 10
- UI Pattern: Read Only
- Fields
- Customer
- Loyalty Program
- Category
- Date
- Earned Points
- Available Points
- Burned Points
- Description
Tab: Burned Points
- Source table: OBLP_Points_Detail
- Level: 1
- Sequence Number: 20
- UI Pattern: Read Only
- Fields
- Burned Points
- Date and Time of Burn
- Burning
New tab in Business Partner: Subscriptions
Tab: Subscriptions
- Source table: OBLP_Subscription
- Level: 2
- Sequence Number: 25 (Placed below Customer)
- UI Pattern: Standard
- Fields
- Loyalty Program
- Category
- Active
- Date and Time of Subscription
- Member ID
- Store
- Currency
- Total Available Points
- Status
- Description
- Process Buttons
- Change Status
Tab: Earned Points
- Source table: OBLP_Earned_Points
- Level: 1
- Sequence Number: 26
- UI Pattern: Standard
- Fields
- Earn Rule
- Date and Time of Earn
- Earned Points
- Available Points
- Card
- Event
- Log
- Manual
- Process Buttons
- Manual Burn
Retail Module - Loyalty Programs for Web POS
- Name: Loyalty Programs for Web POS
- Repository: https://code.openbravo.com/erp/pmods/org.openbravo.retail.loyalty.programs
- Java Package: org.openbravo.retail.loyalty.programs
- DB prefix: OBRLP
New Database Objects
New field in table OBLP_SUBSCRIPTION
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
em_obrlp_store | varchar(32) | Foreign Key to AD_Org. Represents the Store in which the subscription was created | N |
New field in table OBPOS_TERMINALTYPE
Id | Type | Description | Mandatory | Default |
---|---|---|---|---|
em_obrlp_cansubscribe | char(1) | Yes/No field indicating if terminals belonging to this terminal type can start the subscription process. | Y | N |
Client Side Model Extension
The following information will be loaded in WebPOS, either as Terminal Properties or as new Models
Loyalty Program
Loyalty Program will be added as a new Terminal Property (java class extending from QueryTerminalProperty). It will contain the list of Loyalty Programs that are available for the current store. Each program object will include the following information.
- Source package: org.openbravo.retail.loyalty.programs.term
- Class Name : LoyaltyPrograms
- Fields retrieved
- Id
- Name
- Search Key
- Date From
- Date To
- Is Exclusive
- Active
The query to retrieve Loyalty Programs must be extensible so other modules can add extra properties to it.
Loyalty Program Statuses
Loyalty Program statuses will be added as a new Terminal Property (java class extending from QueryTerminalProperty). It will contain the list of statuses defined for all available programs in Web POS. Each status will contain the following information:
- Source package: org.openbravo.retail.loyalty.programs.term
- Class Name : LoyaltyProgramStatus
- Fields retrieved
- Id
- Program Id
- Name
- Sequence
The query to retrieve Loyalty Program Statuses must be extensible so other modules can add extra properties to it.
Subscriptions
The subscriptions of each customer will be added to Web POS as a new model (a new websql table). The table will include the following fields:
- Source package: org.openbravo.retail.loyalty.programs.master
- Class Name : LoyaltySubscriptions
- Fields retrieved
- Id
- Customer Id
- Customer Name
- Program Id
- Program Name
- Status Id
- Status name
- Member Id
- Active
- Starting Date
- Total Points
- _identifier: Concatenation of “Program Name - MemberId - Status Name”
- Remote Preference for the model definition: OBPOS_remote.customer
Since the process will be used from WebPOS, it is required to add it to the Mobile Services definition.
Business Partner Extensions
The following properties will be added to the BusinessPartner model in Web POS:
- Loyalty Program IDs: aggregated value of programs which the BP is subscribed to.
- Number of loyalty programs
- Number of active Subscriptions (active = ‘Y’ and not expired)
- Member IDs: aggregated value of subscription membership IDs (using the hqlaggdist function)
Business Partner Filter Extension
- Loyalty Program IDs: aggregated value of programs which the BP is subscribed to.
- Number of loyalty programs
- Number of active Subscriptions (active = ‘Y’ and not expired)
- Member IDs: aggregated value of subscription membership IDs (using the hqlaggdist function)
- Special case: when the user filters by program and memberId from WebPOS, the memberId property is taken as a subquery, not an aggregated value.
Customer Selector - BPartnerFilter Extension
The BPartnerFilter.java process, which is in charge of executing the customer filtering in web pos in remote mode, needs to be extended to enable conditioned filtering options.
When the user filters both by Member ID and by Program, then that member ID needs to belong to a subscription of that specific program. This requires “smart” parameter setting in the query, requiring a full override of the BPartnerFilter class.
To achieve this, it is required to implement a new java class BPartnerFilterExt.java, extending from BPartnerFilter. The getParameterValues function needs to be overridden to add the programId as a filter only when required.
Additionally, in order to execute this class, and not the default class, when BPartnerFIlter is called, it is required to add the @MobileServiceQualifier(serviceName = "org.openbravo.retail.posterminal.master.BPartnerFilter") qualifier to the class, and also it is required to implement the getPriority method returning a value lower than 100 (the default value).
Client Side Components Extension
Extending the Customer Button
The customer button in the ticket, which implements the enyo kind OB.UI.BusinessPartnerSelector, needs to be extended to accommodate an icon representing the status(es) of the customer’s subscriptions next to the customer name.
To do this, the kind needs to be extended to override the following:
- Its components array, to be able to add the new button.
- The renderCustomer function, which is in charge of redrawing the content of the button (loyalty icon and customer name)
- The initComponents function, so the component is correctly created.
The css style of the icon will follow these rules:
* A subscription will be considered inactive if:
- The subscription itself if defined as active = ‘N’
- The associated program is defined as active = ‘N’
- The associated program is expired.
Extending the Customer Selector Results
The results of the customer selector, which are implemented by the OB.UI.ListBpsSelectorLine kind, need to be extended as well to accommodate the loyalty subscriptions icon next to the shipping and invoicing addresses icons.
This can be achieved by overriding the initComponents function, and adding a new child component with the loyalty icon (Note: the createComponent function accepts an addBefore parameter to define the position of the new component).
The icon will follow the same css rules as in the Extending the Customer Button section.
New Customer Filter by Loyalty Member Id
In order to be able to filter by Membership Id, a new property needs to be added to the OB.Model.BPartnerFilter object. The property will be a simple text-type filter, aggregating all the memberIDs of the customer:
- Name: memberId,
- Column and serverColumn: TBD based on the generated tables
- Filter: true,
- Type: 'TEXT',
- Caption: 'OBRLP_MemberId',
- Location: false
New Customer Filter by Loyalty Program
In order to be able to filter customers by their loyalty program, a new property needs to be added to the OB.Model.BPartnerFilter object. The property will be a list-type filter:
- Name: loyaltyProgram,
- Column: TBD
- Filter: true,
- Type: 'TEXT',
- Caption: 'OBRLP_LoyaltyProgram',
- IsList: true,
- TermProperty: loyaltyPrograms,
- PropertyId: 'id',
- PropertyName: 'name',
- Operator: '='
![]() | Note: If both the memberId and the loyaltyProgram filters are applied, the memberId will be filtered only on the given program. |
New/Edit Customer View and Customer Details View: Subscription Details
A new icon will be added to the New/Edit Customer View and the Customer Details View to handle Loyalty Programs.
In the New Customer View, this row will contain a gray ‘+’ icon . Clicking on the icon will show a message informing the user that the customer needs to be saved before creating a new Loyalty Subscription:
- Popup Title: Save Required
- Message: This Customer form must be saved prior to adding a new Loyalty Program. Please press 'Save' button and then retry.
In the Edit Customer View, this row will contain a gray ‘+’ icon if no Loyalty Subscriptions exist for the customer. If there is already an existing subscription for the customer, it will contain a gray ‘navigate’ icon and some information regarding the existing subscription(s) (if it is a single subscription, its identifier; otherwise, a text showing “ - # records -”).
In any case, clicking on the icon will show a message informing the user that the customer needs to be saved before creating a new Loyalty Subscription:
- Popup Title: Save Required
- Message: This Customer form must be saved prior to managing Loyalty Programs. Please press 'Save' button and then retry.
In the Customer Details View, if no Loyalty Subscriptions exist for the customer, then the Loyalty Program row will contain an active ‘+’ icon. Clicking on the ‘+’ icon will start the subscription process (see below).
If there is already an existing subscription for the customer, the Loyalty Program row will contain an active ‘navigate’ icon to open the Manage Loyalty Subscriptions popup and some information regarding the existing subscription(s) (if it is a single subscription, its identifier; otherwise, a text showing “ - # records -”).
Orange/Active | Gray/Inactive | |
---|---|---|
‘+’ Icon | ![]() | ![]() |
Navigate/Manage | ![]() | ![]() |
Manage Loyalty Subscriptions Popup
The Manage Loyalty Subscriptions Popup will be a new selector which will show the existing subscriptions of a customer.
This popup will be a new enyo kind extending from OB.UI.ModalSelector.
The selector will offer a button to create a new Subscription for the current customer, and clicking on any subscription line will open the Subscription Details view (see below).
Program Selection Popup
It will be possible to start the Add Subscription process from several points: From the Add Subscription button in the Customer Details View popup and from the Add Subscription button on the Manage Loyalty Subscriptions Popup.
In any case, first the process will do the following validations:
- If the terminal type of the current terminal can subscribe customers.
- If the customer is already subscribed to an exclusive program.
If the validations are passed, the Add Subscription process will start with a popup which will allow to select a Loyalty Program. Only active and non expired programs will be shown.
The format of the popup will be similar to the Receiptor Properties or Receipt Line Description/Properties popups.
The popup will present two buttons:
- Cancel: Stops the process and returns to the Customer Details View.
- Next: Validates the selected program (exclusive/non-exclusive and current existing subscriptions) and moves on to the next step if there are no errors.
This popup will be a new enyo kind extending from OB.UI.ModalAction. The body of the popup will be a Scroller component. The popup will also include a newComponents array with the fields of the popup (by default, a combo selector for Loyalty Programs).
Program Specific Data Entry
The second step on the Add Subscription process is to add or review several mandatory customer fields for the program.
By default the program name and the memberId will be shown (both read only), and other modules will be able to add their own fields here.
Fulfilling these fields (except the memberId, which will be sequence based) will be mandatory to continue the process.
It will be possible to define displayLogics for each field (i.e. to make them dependent on the program that has been selected). The default behaviour will be to show only the fields that are defined for a program with a specific searchKey.
The format of the popup will be similar to the Customer Details View popup (extending from the enyo kind OB.UI.Modal).
The popup will present two buttons:
- Cancel: Stops the process and returns to the Customer Details View.
- Save: Validates that all showing fields have been fulfilled. Then calls a backend process to save the subscription (see below). After a successful save, the popup will jump to the subscription details popup.
Program Subscription Details
The third step on the Add Subscription process is a popup which allows to review the information of the subscription that has been created. All information will be read only at this point.
This popup will show the program name, customer name, subscription member id, subscription status, start date and total points. Other modules will be able to add their own fields here.
There will be a Close button to return to the Customer Details View popup/Manage Loyalty Addresses popup.
The format of the popup will be similar to the Customer Details View popup (extending from the enyo kind OB.UI.Modal).
Process Definitions
Save Subscription Process
This process, called from Web POS, will be in charge of creating a new subscription record for a given customer and program. It will generate the memberId for the subscription based on the sequence of the program.
If working in a multiserver environment, it will only be possible to save a subscription against the Central Server.
- Class name: SaveSubscription
- Package: org.openbravo.retail.loyalty.programs.process
- Extends from MultiServerJSONProcess
- Since the process will be used from WebPOS, it is required to add it to the [[Retail:Configuration_Guide#Mobile_Services|Mobile Services definition].
- The process will override/implement the following methods:
- protected JSONObject execute(JSONObject json);
- protected String getImportEntryDataType() returning null;
- Empty, overriden createImportEntry and createArchiveEntry functions
- Protected String getMemberIdentifier();
- The main exec method will return the whole subscription object as a result if there are no errors
- Additionally the process will expose a hook to enable executing custom code while saving the subscription
Hook Definition
- Class name: SaveSubscriptionHook
- Package: org.openbravo.retail.loyalty.programs.process
- The hook will be an abstract class, and will implement a single method:
- public void exec(OBLPSubscription subscription, JSONObject jsonsubscription) throws Exception;
- The hook will be called after the subscription record has been created and the memberId has been generated.