Changes between Initial Version and Version 1 of BluePrint/Sync/CiviCRM


Ignore:
Timestamp:
11/12/12 10:48:17 (9 years ago)
Author:
Dominic König
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • BluePrint/Sync/CiviCRM

    v1 v1  
     1= !BluePrint: CiviCRM Data Synchronization =
     2[[TOC]]
     3
     4== Introduction ==
     5Organisations which use CiviCRM to manage their contacts may want to synchronize person/organisation data with Sahana Eden.
     6
     7== Description ==
     8We 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.
     9
     10== Use-Cases ==
     11
     12Use-cases:
     13
     14  - pull person/organisation data from CiviCRM
     15  - push person/organisation data to CiviCRM
     16
     17Workflows:
     18
     19  - Configure CiviCRM as peer repository for Synchronization (Sahana Eden being the active site)
     20  - Configure resources for CiviCRM Synchronization
     21  - Configure schedule for synchronization with CiviCRM
     22
     23== Requirements ==
     24
     25Sahana-Eden:
     26
     27  - Sahana Eden's Synchronization module can be extended to support CiviCRM as peer repository
     28  - Sahana Eden has XSLT stylesheets to convert S3XML from/into CiviCRM's XML format
     29
     30CiviCRM:
     31
     32  - CiviCRM's REST API can consume XML data sets from POST requests
     33  - CiviCRM provides universally unique keys for every record
     34  - CiviCRM provides synchronization meta-information for every record, most importantly last update time
     35  - CiviCRM's REST API allows filtering by last update time
     36  - CiviCRM's REST API allows other query operators than ''equal'' (e.g. ''less than'' and ''greater than'')
     37  - CiviCRM's REST API supports querying across foreign key contraints
     38  - Authorization for CiviCRM's REST API can be configured via CiviCRM's web UI
     39
     40== Design ==
     41
     42Sahana Eden's synchronization module has been refactored to support multiple repository types using API connector classes.
     43
     44A connector class for CiviCRM has been implemented (currently only supports pull, and only the pr_person resource).
     45
     46To be able to configure synchronization between Sahana-Eden and CiviCRM, you need the following prerequisites:
     47
     48  - the site-key of the CiviCRM instance, which can be found in the civicrm.settings.php file on the server
     49  - the URL of the CiviCRM REST API (this is different for different deployment variants)
     50  - an API key for every user account you want to use the CiviCRM REST API with
     51
     52As of CiviCRM version 4.2, to generate the API key for a user account you need to go through the following steps:
     53
     541. Change the following lines in CRM/Utils/REST.php (around line 98):
     55
     56{{{
     57      // These two lines can be used to set the initial value of the key.  A better means is needed.
     58      //CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key', sha1($result[2]) );
     59      //$api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key');
     60      return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");
     61}}}
     62
     63into:
     64
     65{{{
     66      // These two lines can be used to set the initial value of the key.  A better means is needed.
     67      CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key', sha1($result[2]) );
     68      $api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[0], 'api_key');
     69      //return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");
     70}}}
     71
     722. Send a login request for the respective user account via the REST API:
     73
     74{{{
     75curl 'http://yoursite.org/path/to/civicrm/rest/api/rest.php?q=civicrm/login&key=yoursitekey&name=username&pass=password'
     76}}}
     77
     78Even if this returns an error page, it would still generate the API key for this user.
     79
     803. Revert the changes made in step 1
     81
     824. Send the login request again:
     83
     84{{{
     85curl 'http://yoursite.org/path/to/civicrm/rest/api/rest.php?q=civicrm/login&name=username&pass=password&key=yoursitekey'
     86}}}
     87
     88Now you should get a response like:
     89
     90{{{
     91<?xml version="1.0"?>
     92    <ResultSet xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" >
     93    <Result>
     94    <is_error>0</is_error>
     95    <api_key>fef79ba6c313707eefab72b7c39fb69f</api_key>
     96    <PHPSESSID>b7s22kmthjmst5vtj8ql2uq7iq98pjn2</PHPSESSID>
     97    <key>f0851e9f201fbdb8131239696cb311992987eb87</key>
     98</Result>
     99</ResultSet>
     100}}}
     101
     102Once 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.
     103
     104== Implementation ==
     105
     106  - CiviCRM API connector for Sync is implemented
     107  - A stub for an XSLT stylesheet CiviCRM->S3XML is implemented
     108
     109Note:
     110
     111  - currently only supports "pull" as synchronization method
     112  - currently only supports "pr_person" resource
     113
     114== References ==
     115
     116  - http://wiki.civicrm.org/confluence/display/CRMDOC42/REST+interface
     117  - http://wiki.civicrm.org/confluence/display/CRMDOC42/CiviCRM+data+architecture
     118  - [[wiki:UserGuidelines/Admin/Synchronization]]
     119
     120----
     121BluePrints