= !BluePrint: CiviCRM Data Synchronization =
[[TOC]]

== Introduction ==
Organisations which use CiviCRM to manage their contacts may want to synchronize person/organisation data with Sahana Eden.

== Description ==
We want to use Sahana Eden's Synchronization module to synchronize person/organisation data between Sahana Eden and CiviCRM, with Sahana Eden being the active site to control the data exchange using CiviCRM's REST API.

== Use-Cases ==

Use-cases:

  - pull person/organisation data from CiviCRM
  - push person/organisation data to CiviCRM

Workflows:

  - Configure CiviCRM as peer repository for Synchronization (Sahana Eden being the active site)
  - Configure resources for CiviCRM Synchronization
  - Configure schedule for synchronization with CiviCRM

== Requirements ==

Sahana-Eden:

  - Sahana Eden's Synchronization module can be extended to support CiviCRM as peer repository
  - Sahana Eden has XSLT stylesheets to convert S3XML from/into CiviCRM's XML format

CiviCRM:

  - CiviCRM's REST API can consume XML data sets from POST requests
  - CiviCRM provides universally unique keys for every record
  - CiviCRM provides synchronization meta-information for every record, most importantly last update time
  - CiviCRM's REST API allows filtering by last update time
  - CiviCRM's REST API allows other query operators than ''equal'' (e.g. ''less than'' and ''greater than'')
  - CiviCRM's REST API supports querying across foreign key contraints
  - Authorization for CiviCRM's REST API can be configured via CiviCRM's web UI

== Design ==

Sahana Eden's synchronization module has been refactored to support multiple repository types using API connector classes.

A connector class for CiviCRM has been implemented (currently only supports pull, and only the pr_person resource).

To be able to configure synchronization between Sahana-Eden and CiviCRM, you need the following prerequisites:

  - the site-key of the CiviCRM instance, which can be found in the civicrm.settings.php file on the server
  - the URL of the CiviCRM REST API (this is different for different deployment variants)
  - an API key for every user account you want to use the CiviCRM REST API with

As of CiviCRM version 4.2, to generate the API key for a user account you need to go through the following steps:

1. Change the following lines in CRM/Utils/REST.php (around line 98):

{{{
      // These two lines can be used to set the initial value of the key.  A better means is needed.
      //CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key', sha1($result[2]) );
      //$api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key');
      return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");
}}}

into:

{{{
      // These two lines can be used to set the initial value of the key.  A better means is needed.
      CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key', sha1($result[2]) );
      $api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key');
      //return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");
}}}

2. Send a login request for the respective user account via the REST API:

{{{
curl 'http://yoursite.org/path/to/civicrm/rest/api/rest.php?q=civicrm/login&key=yoursitekey&name=username&pass=password'
}}}

Even if this returns an error page, it would still generate the API key for this user.

3. Revert the changes made in step 1

4. Send the login request again:

{{{
curl 'http://yoursite.org/path/to/civicrm/rest/api/rest.php?q=civicrm/login&name=username&pass=password&key=yoursitekey'
}}}

Now you should get a response like:

{{{
<?xml version="1.0"?>
    <ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
    <Result>
    <is_error>0</is_error>
    <api_key>fef79ba6c313707eefab72b7c39fb69f</api_key>
    <PHPSESSID>b7s22kmthjmst5vtj8ql2uq7iq98pjn2</PHPSESSID>
    <key>f0851e9f201fbdb8131239696cb311992987eb87</key>
</Result>
</ResultSet>
}}}

Once you have achieved this, you can login to Sahana Eden and configure the CiviCRM site as Synchronization repository. Choose "CiviCRM" for repository type, and enter the URL of the REST API as well as the site key into the configuration. Then configure the resources and schedule for this repository, or run synchronization manually.

== Implementation ==
* CiviCRM API connector for Sync is implemented
* A stub for an XSLT stylesheet CiviCRM->S3XML is implemented: https://github.com/flavour/eden/blob/master/static/formats/ccrm/import.xsl

Note:
* currently only supports "pull" as synchronization method
* currently only supports "pr_person" resource

== References ==
* http://book.civicrm.org/developer/current/techniques/api/
* http://wiki.civicrm.org/confluence/display/CRMDOC42/REST+interface
* http://wiki.civicrm.org/confluence/display/CRMDOC42/CiviCRM+data+architecture
* [wiki:UserGuidelines/Admin/Synchronization]