Premium/Sync allows accessing and manipulating all the records stored using RecordBrowser - epesi CRUD engine. Responses generated by all scripts are in XML. The module allows you to retrieve all the records, selected record (with all fields), all the records modified since given timestamp, as well as add new records and edit existing records (with dirty read mechanism).
There are two basic scenarios where Premium/Sync is valuable:
Integration of epesi with other systems. It can be used to retrieve and synchronize the data that is also stored in different system
Simple web interface to display/add data
The module must be installed in epesi to provide the functionality. All the scripts have preventing mechanisms if the module is not installed, completely blocking the access.
If you want to use Premium/Sync as integration tool, then every user in external system should be reflected in epesi and all the actions taken should be identified with respective user login and password. For a simple web interface, we recommend creating a special user, which username and password will be used to access all the functionality.
It's the developer that decides what fields should be used in the synchronization, all fields are accessible through Premium/Sync regardless, even custom fields added on the fly.
All scripts handle requests using $_REQUEST variable, which means both POST and GET methods can be used to send the data. For display purposes, in this manual we'll assume the GET method is being used.
All scripts are placed in modules/Premium/Sync. Assuming that epesi is accessible under http://
Every action performed using Premium/Sync requires authentication. Username and password's md5 hash must be added to every request made. To check md5 hash of your selected password, run this script:
<?php print(md5('your password here')); ?>With username and password ready you can check access to Premium/Sync using the authenticate.php script:
authenticate.php?login=yourlogin&password=md5passwordThe result should be
<response>OK</response>If there was an error, the response will be
<response>ERROR</response>Depending on the error code sent, the problem is:
400 - wrong request, login or password fields missing (possible typo)
401 - wrong username/password
403 - the Premium/Sync module is not installed
Basics
To retrieve multiple records, the get_records.php script should be used. This script requires login, password and module_id parameters. Login and password are the same as in authentication. Module_id is the RecordSet name in epesi (contact, company, crm_meeting, etc.)
The response is as following (example from contacts):
<records>
<record>
<module>contact</module>
<id>1</id>
<primarylabel>Smith</primarylabel>
</record>
<record>
<module>contact</module>
<id>2</id>
<primarylabel>Doe</primarylabel>
</record>
...
</records>The most important part of this response is id. The primarylabel is a text label automatically generated by RecordBrowser. To display all that data, you will still need to retrieve each record individually (more below).
Changes since timestamp
The get_records.php script can also accept optional parameter last_sync_date, a timestamp formatted Y-m-d H:i:s (ex. 1970-01-01 00:00:00). When provided, Premium/Sync will only return records that were created or modified at or after specified timestamp. When using last_sync_date, also deleted records are included in the reply. They contain a new tag in the
<action>DELETED</action>last_sync_date is a useful parameter when integrating a system with synchronization (instead of a full update).
To retrieve a single record, get_record.php script should be used. This script requires login, password, module_id and record_id parameters. Login, password and module_id are the same as in get_records.php. Parameter record_id should be an integer, representing record's internal ID in epesi. On a correct request, the response will be:
<record>
<field>
<id>last_name</id>
<label>Last Name</label>
<value>Bisaga</value>
<rawvalue>Bisaga</rawvalue>
<permission>full</permission>
<type>text</type>
<required>1</required>
<param>
<maxlength>64</maxlength>
</param>
</field>
<field>
<id>first_name</id>
<label>First Name</label>
<value>Arkadiusz</value>
<rawvalue>Arkadiusz</rawvalue>
<permission>full</permission>
<type>text</type>
<required>1</required>
<param>
<maxlength>64</maxlength>
</param>
</field>
...
</record>Each field of the record has a separate section
field_id - this field should be used to identify the field
label - the label of the field (not translated)
value - the value of the field as it should be displayed
rawvalue - the value of the field as it is stored in the database
permission - the level of access to this field, either full or read-only
type - type of the field as set in the RecordSet
required - 1 if the field must have a value set when editing the record in epesi (doesn't affect sync), 0 otherwise
param - this section describes the parameters of the field, used for more advanced synchronization mechanisms
The difference between the value and rawvalue becomes significant when fields of type select and similar is being retrieved. The rawvalue will then hold ID (or IDs) of the record(s) the field is set to, while value will hold the label of the record being referenced.
If record_id provided to the script is invalid, error response is generated:
<response>RECORD_NOT_FOUND</response>Basics
To modify or add new records, the save_record.php script should be used. This script requires login, password, module_id and record_id parameters. Both actions are very similar, the only difference being that when creating a new record, record_id should be set to NEW (case-sensitive), while when modifying existing record record_id should hold the ID of the record to modify and also the last_sync_date parameter is required, a timestamp formatted Y-m-d H:i:s (ex. 1970-01-01 00:00:00). The last_sync_date is used to prevent dirty read changes - modifying a record based on outdated values. The simplest way to force full record overwrite is to set last_sync_date to current timestamp.
In addition to the required fields, you can add any and all fields that should be changed. The proper parameter for each field is that field name prepended by f_. Thus, the proper request to change first_name of contact with id 15 is:
save_record.php?login=yourlogin&password=md5password&module_id=contact&record_id=15&last_sync_date=2012-02-08+12:00:00&f_first_name=ThomasExecuting this script, contact with id 15 will have it's first name changed to Thomas, will all other fields left untouched.
If the script executes properly, the response will depend if it was a new record or modification of existing one. For existing records, the reply is:
<response>OK</response>While for new reocrds it is:
<response>ID</response>Where ID is the id of the newly created record.
Using save_record.php in a web form
While it's possible to use a simple web form with action set to save_record.php to accept new records, it is highly advisable not to do so. First and foremost, user login and md5password would have to be a part of the form, revealing to the user that information. The second issue is the lack of feedback to the user who submits the form, resulting in a plain
<response>OK</response>Instead, it's better to set action to your own script that will parse the response and send it, attaching user login, md5password and even module_id, to save_record.php. Based on response received, you can them display relevant page. In PHP you could simply use file_get_contents('(...)/save_record.php?'.http_build_query($params)), assuming that it's allowed via setting allow_url_fopen variable in php.ini. The alternative is to use curl.
That way you conceal the sensitive data (user login and md5password) and gain control on what is displayed to the user after submitting the form.