Points Transfers in MageRewards v1.9

Starting from MageRewards version 1.9.0 the transfers system has gone through some significant changes. It is now a lot easier to to create custom reasons for your transfers and we made the process of creating transfers a lot easier. In this article we will describe how transfers and it's components can be created and what exactly has changed in version 1.9.0. We assume that you have a background in programming in this article.

Summary: What changed in this version?

• We removed the notion of reference types. We are now differentiating transfers based on reason ids.
• We made it a lot easier to create custom transfer reasons.
• We removed the notion of currency ids from transfers.
• We renamed some of the old fields to make it more obvious what they stand for.

It is now easier to create custom transfer reasons

You can easily create any number of custom transfer reasons now from your own module's configuration file. In this example we will create a custom reason for offline transactions. This is how you would create the reason:

1. Open the configuration file of your module (" /etc/config.xml") and add the following nodes:

<config>
...
    <rewards>
        <transfer>
            <reason>
                <offline>
                    <reason_id>55</reason_id>
                    <label>Offline Transaction</label>
                    <reference_model>sales/order</reference_model>
		</offline>
	    </reason>
	</transfer>
    </rewards>
...
</config>

And now you have a custom reason you can use when creating transfers. But you may be wondering how you can retrieve and use this data. For this reason we created a separate helper class, namely  TBT_Rewards_Helper_Transfer_Reason, with the following methods:

array getReasonData(mixed $reason)

Fetch all related reason data. The Input can be the reason code("offline" in our case) or the reason id;

string getReasonLabel(mixed $reason)

Fetch the reason label. The Input can be the reason code("offline" in our case) or the reason id. In our example this will return "Offline Transaction";

int getReasonId(mixed $reason)

Fetch the reason id from the reason code. In our example this will return "55";

string getReasonCode(mixed $reason)

Fetch the reason code from the reason id. In our example this will return "offline";

Mage_Core_Model_Abstract|null getReasonReferenceModel(mixed $reason)

Fetch the reference model for this reason. The Input can be the reason code("offline" in our case) or the reason id. In our example this will return an instance of Mage_Sales_Model_Order (note that you have to make sure this class exists in your custom module). Will return null if no reference model is specified.

array getAllReasons()

Fetch an array(reason_id => reason_label) with all existing reasons.

What transfer reasons are already present in MageRewards?

MageRewards comes packet with the following transfer reasons:

So how can I create transfers now?

Here is how you would create a transfer for your offline order from our example:

Mage::getModel('rewards/transfer')
->setQuantity(100) //number of points that will be allocated 
->setCustomerId($order->getCustomerId()) 
->setReasonId(Mage::helper('rewards/transfer_reason')->getReasonId('offline'))
->setReferenceId($order->getId()) 
->setStatusId(null, TBT_Rewards_Model_Transfer_Status::STATUS_APPROVED) 
->setComments('You can add any extra details you want to keep in mind here.') 
->save();

How did the database structure change?

Some columns from our transfers table changed. We removed the notion of "reference types" entirely form our transfer logic and dropped the whole rewards_transfer_reference table. There are changes on the rewards_transfer table as well. Some columns just changed, while others were added or dropped entirely. Here is a summary of the changes that happened:

• 2 columns were dropped: 
  • expire_date;
  • currency_id;
• 4 columns were renamed:
  • status became status_id;
  • creation_ts became created_at;
  • last_update_ts became updated_at;
  • last_update_by became updated_by;
• 1 new column was added:
  • reference_id;
• 1 new index was added on( reason_id , reference_id);
• 2 columns now allow a null value:
  • issued_by;
  • updated_by;

(Diagram 1: A visual representation of the database changes)