API used for communication with eWay-CRM web service.
To communicate eWay-CRM web service, we first have to establish connection. This must be done prior to every action we want to accomplish with use of the web service. To do that, we have to load the eway.class.php and create new instance of eWayConnector() with three parameters: service url address (same as the one you use in outlook), username and password.
// Load API
require_once "eway.class.php";
// Create connector
$connector = new eWayConnector('https://trial.eway-crm.com/31994', 'api', 'ApiTrial@eWay-CRM');You can check actions available on your service on [service adress]/API.svc/help. If the help is not enabled on your API have a look at instructions to activate it. You can also see help of the sample web service.
We have put together a list of examples for some basic actions you can use the service for, so don't be shy an try it out.
Example showcasing creation of new Company.
Sample code here.
Example showcasing editing existing Company.
Sample code here.
Example showcasing listing of all existing Companies.
Sample code here.
Example showcasing serching for Company by parameters.
Sample code here.
Example showcasing deletion Company.
Sample code here.
Example showcasing creation of simple relation.
Sample code here.
Example showcasing listing contacts linked to company.
Sample code here.
Example showcasing creation of new Invoice and items on it.
Sample code here.
Example showcasing listing all changes on contacts from last check.
Sample code here.
Example showcasing creation of task with basic link to a document.
Sample code here.
Example showcasing changing project status.
Sample code here.
Example showcasing manipulation with additional fields.
Sample code here.
eWay-CRM server component (web service) stores data uploaded from various clients (Outlook Addin, Mobile App, API...). One of the main features of eWay-CRM is sharing data among users (among clients). When permissions configuration allows, multiple users have the possibility to modify the same data records at the same time. Making a change at the same time means to load the record, change it and save it while another client is doing the same steps and loads the data before the first client saves it. Because of the client software’s ability to work offline, this situation comes up more often than one would expect.
eWay-CRM deals with this subject in a similar way to Subversion (SVN) or Git. Every data record has its own revision number called ItemVersion. This field contains integer, which is increased on every change made to the item. Every client software should consider the very latest revision of the data record before any change is uploaded to the server. Then by uploading the data record with the field ItemVersion increased by one, the client tells the server that it has taken the latest revision into account. The server processes the uploads sequentially. Hence, when two clients change the same item at the same time, there is always one client who loses – does not actually take the change made by the faster client into account. This slower client uploads the ItemVersion lower or equal to the current state. The server component does not allow such uploads and returns error code rcItemConflict (or rcItemAlreadyUploaded).
The logic described above implies that these conflicts must be solved on the client side. eWay-CRM for MS Outlook does it in cooperation with the user (see more in eWay-CRM Documentation ). Nevertheless, eWay-CRM API is a middle-layer software between eWay-CRM server component and 3rd party clients. By default, the API solves these conflicts for you.
Of course, you always have the option to not specify ItemVersion field at all. In that case the API determines the right ItemVersion for you and works with the incremented value. No conflict appears on the background then. When you set the version integer high enough, no conflict solving is needed as well. When you upload an item with ItemVersion lower or equal to the current server state, the API solves the conflict by merging the uploaded data with the data stored on the server. For example, if you download the item, change something and send it back without creating a new object, you probably send back the same ItemVersion as you downloaded. API will do the merging in this saving without you even notice.
How does this automatic merging work? Very simply. The data sent into the API always win, except of nulls. In other words, the API writes all the changes into database except the fields where an existing value would be erased.
Wanna see it for real? Check this example out.
If you want to make sure no merge is done or you just want to really take the very latest version into account, you can always switch the conflicts on by specifying the dieOnItemConflict flag. Then you will get the return codes rcItemConflict and rcItemAlreadyUploaded and you will have to deal with them yourself. The usage of this flag is shown in this example.
To ease understanding folder names, look here.
This php class handles eWay-CRM API sessions automatically. It opens an API session once the first call is done. Use one instance of this class for all the calls you are going to make in order to not open a new session for each call. If you still get the error There is too many sessions, make sure you close the API session with logOut() method at the end of the class instance lifetime.