Knowledge Base
Points System Module::Item no. 1
Points System Module  

Flow Management Tutorial Part 1: Basic Commands

Flow Management is the main workforce of this module.  This allows you to create unique behaviour for your system through scripting.  It can be daunting at first but following the examples below will allow you to understand easily how to use the script.

Always remember that the PSM, CDB and WALLET modules works hand in hand.  PSM tracks the points as well as provide the instructions on how the points, wallets or variables within the system are tracked and modified.

Table of Contents

I. Assumptions

II. Examples

A. Points and Cash Flow

B. Field Modification

C. Conditions

 

Assumptions

For all the examples below, we have the following assumptions.

For Clients Database (CDB) we assume the following fields were defined by the user:

  • Field named 'UID' with type 'USER ID'
  • Field named 'AC' with type 'ACTIVATION CODE'
  • Field named 'RID' with type 'REFERRER ID'
  • Field named 'CHECKBOX1' with type 'CHECKBOX'
  • Field name 'COUNTER1' with type 'NUMERIC'
  • Field name 'VALIDITY' with type 'DATE'

On your site, you might have named the fields differently, just take note of the field type. We strongly suggest you follow the field names for this tutorial to avoid confusion.

For the Wallet Module (WALLET), we assume the following default transaction types are defined on the system. On a normal installation, user doesn't need to add these info, it should be automatically added.

  • 4000100 - Credit memo for inserting positive values or adding money to the wallet of a user
  • 4000200 - Debit memo for inserting negative values or subtracting money to the wallet of a user

For the Points System Management  (PSM), we assume the following default transaction types are defined on the system.  On a normal installation, user doesn't need to add these info, it should be automatically added.

  • 1 - Credit for inserting positive values or adding points to the user
  • 2 - Debit for inserting negative values or subtracting points to the user

For Levels Management, we assume the following levels are defined by the user under Points System Management::Levels Management (PSM::LM)

  • Level Code: ABC
    • Level 1 - Fixed Amount of 10 CV or PV
    • Level 2 - Fixed Amount of 20 CV or PV
    • Level 3 - Percentage Amount of 5% of whatever the input

To create a level code, go to Points System Management::Levels Management (PSM::LM), then click the add.  Enter a level code, it can be anything like ELITE, VIP, PRO whatever fancies you as long as you are consistent with its usage, but for this tutorial, it is best to stick with ABC.  Type in any name and detail that will easily remind you of what it does.  Click submit when you are done to save the information. Go back to list view and the newly created level code should be visible.  Click at the code field to display the levels, there should be no levels for now as it was just recently created. Click on the 'Add level' button to show the form fields.  Fill-in the level field which normally starts with 1, and the desired amount or percentage or both.  Click the 'add entry' button to save and do the same with other levels.

For the user structure, we also assume the following registered users on the system.

No description

You can manually add these users through Account Management::User Management via the add button at the bottom of the list.

Before you can create new Flow entry which is the real purpose of this 'tutorial by example', you will also need to create a Project under Points System Management::Projects Management (PSM::PM) and Team or Teams under Points System Management::Team Management (PSM::TM). 

To create a Project, go to Points System Management::Projects Management (PSM::PM), then click add.  Fill-in the name and detail field with any sensible info, it doesn't matter what you put in as long as it is relevant to your project but for this tutorial, you could just use 'Tutorial' as project name. Click Submit afterwards.

To create teams, go to Points System Management::Team Management (PSM::TM), then click add.  Normally, you start with 1 as your first ID and increment it with new team.  For this project, add the following:

  • ID=1, Name=Team A
  • ID=2, Name=Team B

And we're done with the test environment for this tutorial,  we can now proceed with tutorials by examples.

Examples

Please note that the scripts are placed at the 'Options' field of Flow Management.  It is located at Points Management::Flow Management or PSM::FM.  Create or edit an existing flow, fill-in name and detail to easily identify it, select your project and the default team, then the Options field, below are what you can put on it.

A. Points and Cash Flows

1. CUID=102,4000100

This is the most basic command, the C stands for CV or cash value which means we are modifying the wallet of the user initiating this event.  UID is the field name.  In this example, 102 is credited to the initiating user with the transaction inserted as transaction type 4000100 or credit memo.

2. PUID=10,1

Similar to above but the P is for PV or point value which means we are modifying the points of the user initiating this event. In this example, 10 points will be credited to the initiating user with the transaction inserted as transaction type 1 or credit.

REMEMBER
C stands for CV
P stands for PV

To simplify out language, 100 CV means we added 100 to the wallet, -200 CV means we subtracted 200 to the wallet.  300 PV means we added 300 points to the points system and -400 PV means we subtracted 400 points to the points system.

3. CRID->UID=100,4000100

This time, instead of crediting directly to the initiating user, we now credit to whoever is at the RID of the user.  Example, if the initiating user is User2, and RID of User2 is User1, then User1 will receive 100 CV.  The above command can be read as "Credit RID referenced by UID" or for completeness "Credit 100 CV trantype 4000100 on RID referenced by UID"

4. PRID->UID=-200,2

And this is the PV counterpart of sample #3 which deducts 200 PV to whoever is at the RID of the user.  Example, if the initiating user is User2, and RID of User2 is User1, then User1 will be deducted -200 PV.

5. CRID[ABC]->UID=100,4000100

We now introduce levels,  Levels Management allows us to define what the users above the initiating user will receive depending on how far from the initiating user they are located. The above command instructs the system to use the defined values of level code ABC and apply it to the user listed at the RID field of the initiating user and follow-through the RID of the credited user until all levels have been used or no more user under the RID field.  It might be hard to understand now but the following paragraphs will ellaborate that in detail.

For this example, refer to the diagram above on user structure or placement.  Let's assume the initiating user is User8.  Knowing that our Level code ABC has 3 levels, the following users will be affected, User4, User2 and User1. To make it clearer:

  • User8 is Level 1 of User4
  • User8 is Level 2 of User2, with User4 as Level 1
  • User8 is Level 3 of User1, with User4 as Level 2 and User2 as Level 1

The level definition means whoever is position at a certain level, will receive whatever amount is defined. Back to our assumption, we can now determine what value each affected users will receive.

  • User8 being Level 1 of User4, User4 will receive a fixed amount of 10CV ignoring the input value of 100 on the flow command, but will still use the trantype of 4000100
  • User8 being Level 2 of User2, User2 will receive a fixed amount of 20CV
  • User8 being Level 3 of User1, User1 will receive a percentage amount which is 5% of the input value, 5% of 100 is 5CV, so User1 will receive 5CV.

In summary, User8 being the event initiator, based on the command script above, this is what the users will receive:

  • User4 = 10CV
  • User2 = 20CV
  • User1 = 5CV (5% of 100CV)

Let's say the event initiator becomes User9, based on the command script above, this is what the users will receive:

  • User6 = 10CV
  • User3 = 20CV
  • User1 = 5CV (5% of 100CV)

Let's say the event initiator becomes User5, based on the command script above, this is what the users will receive:

  • User2 = 10CV
  • User1 = 20CV
  • Unless User1 has someone above it, it gets 5CV, but since none on our example, that level is just skipped or ignored.

B. Field Modification

Previously, we learned how to add/subtract values to our wallet and points system using the C and P commands respectively, on this section, we now introduce the F command which modifies the field that can be useful for a lot of things such as tracking a counter, flagging users, updating expiry or user and many more. 

The general format for an F command is

F[initiating field]=[modified field],[value]

Your initiating field are similar to the previous examples which are usually your type 'User ID', 'Referrer ID', or combination with levels. Examples based on the above are:

  • FUID
  • FRID
  • FRID[ABC]->UID

Your modified field is the same field you defined under Clients Database::Fields Management.  Since fields can have different types, the value field can have different behaviour depending on the field type.  Below are the list of types and how the value field will be interpreted:

  • Numeric - value is added to the original value of the field.
  • Timestamp/Date - value is added to the original value of the field, but the value and the original value are interpreted as epoch.
    If the value is a text 'now', it will replace the original value with the current date and time.
  • Checkbox - value for checkbox type can only be 'checked' or blank.

1. FUID=COUNTER1,100

In this example, the event initiator will have their COUNTER1 field modified by adding 100 to whatever the original value it has.  If the COUNTER1 field originally contains 20, it becomes 120.

2. FRID->UID=CHECKBOX1,checked

This will change the CHECKBOX1 field of the user under the RID field of the user initiating this event.  The value will become 'checked' regardless of what it was originally. 

3. FRID->UID=VALIDITY,120

VALIDITY is a date field based on our setup above.  The value 120 is in seconds, or 2 minutes, so whatever the original value of the VALIDITY field, we are to add 2 minutes on it. 

4. FRID->UID=VALIDITY,-2592000

Similar to example #3, 2592000 is in seconds and is equivalent to 30days.  Since it is negative, we are subtracting 30 days from the original value of the VALIDITY field.

5. FRID[ABC]->UID=COUNTER1,100

The above command instructs the system to use the defined values of level code ABC and apply it to the user listed at the RID field of the initiating user and follow-through the RID of the next user until all levels have been used or no more user under the RID field.

For this example, refer to the diagram above on user structure or placement.  Let's assume the initiating user is User8.  Knowing that our Level code ABC has 3 levels, the following users will be affected, User4, User2 and User1. To make it clearer:

  • User8 is Level 1 of User4
  • User8 is Level 2 of User2, with User4 as Level 1
  • User8 is Level 3 of User1, with User4 as Level 2 and User2 as Level 1

This means User4, User2 and User1 will have their COUNTER1 field incremented by 100.

REMEMBER
C stands for CV, meaning we modify the wallet
P stands for PV, meaning we modify the points
F stands for Fields, meaning we modify the field value.

C. Conditions

Some system design may require conditions to make the system more intelligent. In this section, we will learn how to apply conditions to the commands we previously learned.

In the past section, we recall that the basic flow command is formatted as follows:

[command][initiating field]=[parameter 1],[parameter 2]

command as we recall can be C, P or F (and others that will be discussed on advance levels), which corresponds to CV, PV and Field.

initiating field as we recall is the field defined at Cliends Database::Field Management or CDB::FM which are of types 'User ID', 'Referrer ID' and/or combination with or without levels as defined at Points System Management::Levels Management.  We had the following as our examples: UID, RID->UID and RID[ABC]->UID

parameter1 and parameter2 depends on what command was used, whether it is C or P which means parameter1 becomes the value and parameter2 becomes the transaction type, or command F which means parameter1 becomes modified field and parameter2 becomes the value.

Let us call that whole string as FLOW COMMAND to  provide easy distinction between the command we previously learned and the new set of command that will make up the conditions.

For the conditions, we normally have a PRE-CONDITION or we call it PRECOND for short, and a POST-CONDITION or POSTCOND.  The format for both is as follows:

[type][operator][field]=[value]

type is how we interpret the field, it can be as follows:

  • s for string type
  • d for date type
  • n for numeric
  • a for amount
  • b for base

Each type will be discussed in details later when used on an example.

operator is how we compare the field and the value, it can be as follows:

  • eq for equal
  • ne for not equal
  • gt for greater than
  • lt for less than
  • ge for great than or equal
  • le for less than or equal

field is whatever is defined at Cliends Database::Field Management or CDB::FM.

value is for comparing what is originally stored at the field.

PRECOND and POSTCOND are used in conjunction with the FLOW COMMAND in the following manner:

{PRECOND}FLOW COMMAND{POSTCOND}

Let us now see this format with real commands on it by citing examples.

NOTE

1. {seqCHECKBOX1=checked}FUID=COUNTER1,100

In the above example, we have a PRECOND defined as {seqCHECKBOX1=checked} and a flow command defined as FUID=COUNTER1,100.  The PRECOND is interpreted as:  the FLOW COMMAND will be executed only if CHECKBOX1, interpreted as string (note the s), is equal (note the eq) to the value checked.

2. {seqVALIDITY=}FUID=VALIDITY,now

In this example, we check the value of VALIDITY field if its blank, if it is then we set the value as 'now' or the current date and time.

3. {nltCOUNTER1=1000}FUID=COUNTER1,100

In this example, the PRECOND checks if COUNTER1 is less than 1000, if it is, the FLOW COMMAND adds 100 to COUNTER1. 'n' in this example means we are comparing numerically.

4 {dgeVALIDITY=now}PUID=100,1

The PRECOND checks the VALIDITY field if the date (as denoted by 'd' command) is greater or equal to 'now' or the current date and time, if it is then the FLOW COMMAND will add 100 PV to the initiating user.

Sometimes, there is a need for multiple conditions, they are either 2 or more conditions that needs to be satisfied at the same time, or sometimes 2 or more conditions that only require 1 condition to be satisfied, or a combination of both.  These are called AND and OR conditions.  The following format can be used to obtain that effect:

For AND conditions, we just append the '&' or ampersand sign between the conditions within the curly brackets { and }.

  • {PRECOND&PRECOND} - 2 conditions, both conditions needs to be satisfied.
  • {PRECOND&PRECOND&PRECOND} - 3 conditions, all needs to be satisfied to execute the FLOW COMMAND

For the OR conditions, we enclose each condition within the curly brackets [ and ].

  • {PRECOND}{PRECOND} - 2 conditions, either of the 2 needs to be satisfied to execute the FLOW COMMAND
  • {PRECOND}{PRECOND}{PRECOND} - 3 conditions, either of the 3 needs to be satisfied to execute the FLOW COMMAND

And for combinations, we just mix the 2 together, AND separated with & and OR enclosed with curly brackets [ and ].

  • {PRECOND1&PRECOND2}{PRECOND3} - 3 mixed conditions, either PRECOND3 is true, or PRECOND1 and PRECOND2 both needs to be true to execute FLOW COMMAND

Note that this also applies to POSTCOND.

Let us now see this format with real commands on it by citing examples. 

Notice Samples below may extend to the next line due to very long command.  Please ensure that they only occupy 1 line on the actual options field.

5. {dgeVALIDITY=now&nltCOUNTER1=1000}CUID=1000,4000100

In this example, we have an AND condition, both VALIDITY field should be 'greater or equal' to 'now' or current date/time AND the field COUNTER1 should be 'less than' 1000 before we can execute the FLOW COMMAND which adds 1000 CV to the initiating user.

6. {dgeVALIDITY=now}{nltCOUNTER1=1000}CUID=1000,4000100

Similar to #5, but this time we change it from AND condition to OR condition, meaning, EITHER field VALIDITY should be 'greater or equal' to 'now' OR the field COUNTER1 should be less than 1000 to execute FLOW COMMAND which adds 1000 CV to the initiating user

7. {dgeVALIDITY=now&nltCOUNTER1=1000}{seqCHECKBOX1=checked}CUID=1000,4000100

This time a combination of AND and OR conditions. Either CHECKBOX1 field should be 'equal' to checked OR both VALIDITY field should be 'greater or equal' to 'now' or current date/time AND the field COUNTER1 should be 'less than' 1000 to execute the FLOW COMMAND of adding 1000 CV to the initiating user.

 

So far we have example usage only of PRECOND. The POSTCOND functions a bit differently, while PRECOND is used to determine whether the FLOW COMMAND is executed or not, POSTCOND is used in conjunction with levels to determine if a particular level gets credited based on the FLOW COMMAND.  It sounds tricky, but with the examples and detailed description below, it will make a lot of sense.

8. CRID[ABC]->UID=100,4000100{seqCHECKBOX1=checked}

If you recall one of our examples above under A.5, we have a FLOW COMMAND of CRID[ABC]->UID=100,4000100, we simply added the POSTCOND {seqCHECKBOX1=checked}.  With the POSTCOND in place, aside from iterating each levels to determine or compute for the CV that will be credited to the user of a particular level, it will check if the user of that particular level has CHECKBOX1 field containing a string value of 'checked'.  To elaborate on the example, let's have an assumption of the following content of CHECKBOX1 field of each user:

  • User1 has CHECKBOX1 = checked
  • User2 has CHECKBOX1 = '' (blank)
  • User4 has CHECKBOX1 = checked

Based on the example on section A.5, let's assume the initiating user is User8.  We now have the following result:

  • User8 being Level 1 of User4, User4 will receive a fixed amount of 10CV ignoring the input value of 100 on the flow command, but will still use the trantype of 4000100.  It will be credited because CHECKBOX1 of User4 is 'checked' and satisfies the POSTCOND.
  • User8 being Level 2 of User2, User2 should receive a fixed amount of 20CV, but because User2 has blank CHECKBOX1 field, POSTCOND requirement was not satisfied, User2 is then skipped from receiving or being credited with CV.
  • User8 being Level 3 of User1, User1 will receive a percentage amount which is 5% of the input value, 5% of 100 is 5CV, so User1 will receive 5CV. It will be credited because CHECKBOX1 of User1 is 'checked' and satisfies the POSTCOND.

9. {dgeVALIDITY=now}CRID[ABC]->UID=100,4000100{seqCHECKBOX1=checked}

In this example, we now used both PRECOND and POSTCOND.  This is not actually very far from what example #8 above does, the only difference is that before the whole FLOW COMMAND and POSTCOND is executed, it first check the PRECOND which is based on the initiating user.  Assuming our initiating user is User8, it first checks if VALIDITY field is 'greater than or equal' to 'now' or the current date/time.  If it satisfy the condition, the rest of the example just functions like #8.

With the introduction of PRECOND and POSTCOND, we have more flexibility on how we can design our system to distribute PV and CV based on user qualifications.