Developers/Concepts/Howto connect to Tine 2.0 over JSON-RPC

From Tine 2.0 - Wiki

< Developers

From the beginning Tine 2.0 is separated into two layers. The PHP based backend which runs on the webserver and the JavaScript based frontend which runs in the browser on the users computer.

JSON-RPC

These two layers communicate over JSON-RPC. JSON-RPC is a lightweight protocol which perfectly suites the needs of webbased applications, as we in fact can transport whole JavaScript arrays and objects. This makes creating the requests and parsing the response on the client side very trivial. Tine 2.0 speaks JSON-RPC version 2.0.

JSON-SMD

Another important piece is JSON-SMD. The Service Mapping Description (SMD) is a JSON representation of services and its parameters provided by a JSON-RPC server. If you are able retrieve the SMD you have a list of all functions available and accessible by your JSON-RPC client.

Putting it together

As JSON-RPC is very easy to implement, you can find implementations for various languages. While the PHP JSON-RPC client is bundled with Tine 2.0, it is known that there also exist implementations for Java and Perl. The client bundled with Tine 2.0 also supports JSON-SMD.

How to retrieve the Service Mapping Description (SMD)

The Tine 2.0 JSON-RPC server delivers the JSON-SMD by sending a request with the method set to NULL and the request-type being application/json-rpc. Depending on the users rights, you will receive a list of all functions available. If you log in, you should request the SMD again.

Sending an JSON-RPC request

While the JSON-RPC protocoll is documented very well, you need to sent a special key after login. This key is called jsonKey and must be sent as header X-Tine20-JsonKey with any request after login. You receive the jsonKey in the resonse of a successful login. Any Tine 2.0 application(tinebase, addressbook, callender,...) has its own namespace for method names. Any methods for the calendar are prefixed whit calendar for example.

If your implementation does not support JSON-SMD you can also simply have a look at the Frontend/Json.php classes an the specific application directories. We are also working on providing a webpage documenting all methods available over JSON-RPC.

To find out what you need to sent, you can also install the Firebug extension in your Firefox browser and have a look at the requests sent by Tine 2.0.

A real life PHP example

Based on Zend_Service_Client which adds a small layer on top of Zend_Json_Client we will provide you a small example how to add a new contact and a new lead over JSON-RPC.

<?php
// url of your Tine 2.0 installation 
$tine20Url = 'http://tine20/index.php';
// login name 
$tine20Loginname = 'loginname';
// password
$tine20Password = 'password';
// id of addressbook container
$addressbookContainerId = '9';
// id of CRM container
$crmContainerId = '14';

// intialize composers autoloader
require 'vendor/autoload.php';

// initialize Tine 2.0 service
$tine20 = new Zend_Service_Tine20($tine20Url);

// login into Tine 2.0
$response = $tine20->login($tine20Loginname, $tine20Password);
var_dump($response);

// call Tinebase.getAllRegistryData directly
$result = $tine20->call('Tinebase.getAllRegistryData');

// call Tinebase.getAllRegistryData using a Tinebase proxy class
$tinebase = $tine20->getProxy('Tinebase');
$result = $tinebase->getAllRegistryData();

// get a proxy class for the Addressbook namespace
$addressbook = $tine20->getProxy('Addressbook');
// create a new contact
$contact = $addressbook->saveContact(array(
  'n_family' => 'Picard',
  'n_given' => 'Jean-Luc',
  'container_id' => $addressbookContainerId
));

// get a proxy class for the CRM namespace
$crm = $tine20->getProxy('Crm');
// create a new lead in the CRM and assign contact created above as costumer
$crm->saveLead(array(
'lead_name' => 'Test lead',
'leadstate_id' => 1,
'leadtype_id' => 1,
'leadsource_id' => 3,
'start' => '2009-11-13 21:00:00',
'description' => 'Added via Tine 2.0 Service',
'container_id' => $crmContainerId,
'relations' => array(array(
  'type' => 'CUSTOMER',
  'related_record' => $contact
  ))
));

// logout from Tine 2.0 
$tine20->logout();