Projects:Loyalty Programs/Technical Documentation

Contents 1 Introduction 2 Core Module - Loyalty Programs 2.1 New Database Objects 2.2 Application Dictionary Definition 2.2.1 New List References 2.2.2 New Processes 2.2.2.1 Burn Run Process 2.2.2.2 Change Status 2.2.2.3 Copy Burn Run Configuration 2.2.2.4 Manual Burn 2.2.2.5 Set As Ready 2.2.2.6 Simulate Burn Run 2.2.3 New Auxiliary Inputs 2.2.4 New Callouts 2.2.5 New Validations 2.3 Windows, Tabs and Fields 3 Retail Module - Loyalty Programs for Web POS 3.1 New Database Objects 3.2 Client Side Model Extension 3.2.1 Loyalty Program 3.2.2 Loyalty Program Statuses 3.2.3 Subscriptions 3.2.4 Business Partner Extensions 3.2.5 Business Partner Filter Extension 3.2.6 Customer Selector - BPartnerFilter Extension 3.3 Client Side Components Extension 3.3.1 Extending the Customer Button 3.3.2 Extending the Customer Selector Results 3.3.3 New Customer Filter by Loyalty Member Id 3.3.4 New Customer Filter by Loyalty Program 3.3.5 New/Edit Customer View and Customer Details View: Subscription Details 3.3.6 Manage Loyalty Subscriptions Popup 3.3.7 Program Selection Popup 3.3.8 Program Specific Data Entry 3.3.9 Program Subscription Details 3.4 Process Definitions 3.4.1 Save Subscription Process 3.4.1.1 Hook Definition

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.

Back to Main Project page

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
• 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:

Subscription status	Css class name	Icon
If the customer is not subscribed to any loyalty program	No class	No icon
When customer subscribed to an exclusive loyalty program which is inactive (inactive or expired)*	subscription-exclusive-inactive
When customer subscribed to several programs, and all of them inactive (inactive or expired)*	subscription-normal-#-inactive Where # will be the number of subscriptions (1-5)
When customer subscribed to an exclusive loyalty program which is active (not expired)*	subscription-exclusive-active
When customer subscribed to several programs, and all active*	subscription-normal-#-active Where # will be the number of subscriptions (1-5)
When customer subscribed to several programs, some active and some inactive*	subscription-normal-#-mixed Where # will be the number of subscriptions (1-5)

* 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: '='

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.