README

Wabel's Zoho-CRM Synchronizer

What is this?

This project is a set of tools to help you synchronize your database with ZohoCRM records. It is built on top of the ZohoCRM ORM. Before reading further you should get used to working with ZohoCRM ORM, so if you do not know this library, STOP READING NOW and follow this link.

How does it work?

Zoho-CRM Synchronizer does not assume any database model in your application. You could be using Doctrine, PDO, MySQL, PostgreSQL or store data into MongoDB, you can use Zoho-CRM Synchronizer. It also means that you will be in charge of storing data into your database.

Zoho-CRM Synchronizer contains a ZohoSynchronizer class, with a sync() method that synchronizes your database with Zoho (in both ways).

Each instance of ZohoSynchronizer can synchronize a Zoho module (for instance "Contacts", or "Accounts"). The ZohoSynchronizer constructor expects 2 parameters:

The ZohoDao of the module (generated by the ZohoCRM ORM library)
A mapper implementing the MappingInterface. It is up to you to write this mapper.

use Wabel\Zoho\CRM\ZohoClient;
use Wabel\Zoho\CRM\Sync\ZohoSynchonizer;

// First we need to create the ContactZohoDao
$zohoClient = new ZohoClient($zohoAuthToken);
$contactZohoDao = new ContactZohoDao($zohoClient);

// Then we need to instantiate the mapper
$contactMapper = new MyContactMapper();

// Finally, we can call the synchronizer:
$synchronizer = new ZohoSynchonizer($contactZohoDao, $contactMapper);
$synchronizer->sync();

The Synchronizer class will be in charge of talking to Zoho and fetching the latest modified records. Your mapper will be in charge of mapping those Zoho records to your database and vice-versa.

A bit of vocabulary

In the rest of this document, we will use 2 terms quite often:

an application bean is an object you have in YOUR application and that represents a row in database. For instance, if you are using Doctrine, this would be an array of Doctrine entities. If you are using TDBM, this would be an array of TDBM beans...
a Zoho bean is an object representing a Zoho record. These objects are generated by the ZohoCRM ORM library.

The goal of the mapper is to map fields between application beans and Zoho beans.

Writing a mapper

You must write a mapper for every kind of record you want to synchronize.

Your mapper must implement Wabel\Zoho\CRM\Sync\MappingInterface. This interface provides these methods:

use Wabel\Zoho\CRM\Sync\MappingInterface;

class MyContactMapper implements MappingInterface {
        /**
         * Returns an array of application beans that have been modified since the last synchronisation with Zoho.
         *
         * @return \object[]
         */
        public function getBeansToSynchronize()
        {
            // This method should return a list of beans representing your database rows.
            // For instance, if you are using Doctrine, this would be an array of Doctrine entities.
            // If you are using TDBM, this would be an array of TDBM beans...
        }


        /**
         * Returns a Zoho Bean based on the bean passed in argument
         *
         * @param  object            $applicationBean
         * @return ZohoBeanInterface
         */
        public function toZohoBean($applicationBean)
        {
            // The goal of this method is to create a new Zoho bean based on the application bean passed in parameter.
            // It should return a Zoho bean matching your bean.
        }
    
        /**
         * Returns a Zoho Bean based on the bean passed in argument
         *
         * @param  ZohoBeanInterface $zohoBean
         * @return object
         */
        public function toApplicationBean(ZohoBeanInterface $zohoBean)
        {
            // This method will receive the Zoho bean from Zoho.
            // It should
            // 1- get the ZohoId (using $zohoBean->getZohoId() )
            // 2- check in your database if a bean with this ZohoId exists or not
            // 3-a- If the bean exists in database, merge the Zoho bean into the application bean
            // 3-b- If the bean does not exist in database, create the application bean from the Zoho bean
        }
    
        /**
         * Function called when an application bean was successfully stored in Zoho.
         * Used to store the ZohoID and last modification date in the bean passed in parameter.
         *
         * Note: in case an update is performed and the ZohoID stored in app does no more exists
         * in Zoho (for instance if the record has been deleted in Zoho), the $zohoId and the
         * $modificationDate will be null.
         *
         * @param object    $applicationBean
         * @param string    $zohoId
         * @param \DateTime $modificationDate
         */
        public function onSyncToZohoComplete($applicationBean, $zohoId, \DateTime $modificationDate)
        {
            // This function is called after an application bean has been stored into Zoho.
            // Zoho returns a ZohoID, and a modification time. You must store both information in the application bean.
            
            // Note: if $zohoId and $modificationDate is null, it means the ZohoID that was stored on the
            // application side is no more valid (either because the record has been deleted in Zoho or has been
            // merged)
        }
    
        /**
         * This function should return the last Zoho modification date of a record saved in YOUR database.
         * The date must be returned as a \DateTime object.
         * Note: when a Zoho bean is inserted, the last modification date is passed to the `onSyncToZohoComplete`.
         * You should store that date in the database.
         *
         * @return \DateTime
         */
        public function getLastZohoModificationDate() {
            // You should perform a query in your database and return the "max" modification date
            // stored into your application bean table.
        }

}

wabel / zoho-crm-sync

Maintainers

Details