.. _web_contacts:
Web Service Contacts
====================
.. contents::
:local:
:depth: 3
Overview
--------
Acrobits apps may use an external web service to load user's contacts (address book). Web Service Contact Source can be
used instead of native phone address book, or both phone address book, web service contacts and also CardDAV Contact
Source can be used together. In case multiple contact sources are defined, the GUI lets the user switch between
different sources.
Web Service contacts are obtained in two steps:
#. The app calls the web service and receives response. This response is expected to be in JSON format and should contain an array of contact objects.
If you are already working with an existing contacts web service that returns an XML response, you may still use that depending on the response format.
Please refer to :ref:`contacts-transformation` and :ref:`contacts-wscontactsxpath` to learn more about utilising an existing XML contacts web service.
#. Transform the returned response into an internal json contact representation used by the app
The apps will call the web service periodically at a configurable interval (the default is 180 seconds).
Contacts Source Web Service
---------------------------
Parameter templates for Contacts Source Web Service can use any variables from :ref:`global-params`
and :ref:`account-params` scopes.
The web service is configured on global level, either by Cloud Softphone portal, or by setting the appropriate prefKeys
directly for apps which use Acrobits SDK. The properties follow the general Acrobits Web Service Definition model, with
prefix ``wsContacts``:
``wsContactsUrl``
~~~~~~~~~~~~~~~~~
Contains the URL, including URL scheme, of the web service, possibly also with query string.
Example:
.. code-block:: xml
https://example.com/contacts/?u=%account[username]%&p=%account[password]%
``wsContactsMethod``
~~~~~~~~~~~~~~~~~~~~
The HTTP method to use. Typically ``GET`` or ``POST``. The default is ``GET``.
``wsContactsPostData``
~~~~~~~~~~~~~~~~~~~~~~
If filled in, the app will use POST request to call the web service.
Example ( for application/x-www-form-urlencoded):
.. code-block:: none
u=%account[username]%&p=%account[password]%
Example ( for application/json ):
.. code-block:: json
{
"username" : "%account[username]%",
"password" : "%account[password]%"
}
``wsContactsContentType``
~~~~~~~~~~~~~~~~~~~~~~~~~
Specifies the value of Content-Type header to be sent in POST request. If not specified, the app will default to
``application/x-www-form-urlencoded``
``wsContactsAuthUsername``, ``wsContactsAuthPassword``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In case your server uses HTTP authentication, you can provide the username and password here. The apps support
``Basic`` and ``Digest`` authentication, but note that ``Basic`` authentication will only work when using https url
scheme. The app will not send passwords over plaintext connection.
Example:
.. code-block:: xml
%account[username]%
%account[password]%
``wsContactsRefresh``
~~~~~~~~~~~~~~~~~~~~~
The period in seconds which determines how often will the app call the web service. The default is 180 seconds. The
web service will only be called when the app is running in foreground.
.. _contacts-wscontactsxpath:
``wsContactsXPath``
~~~~~~~~~~~~~~~~~~~
In case the web service response returns XML which contains other information than just the list of contacts, this
parameter tells the app where to look for contact data. See the examples for more information.
``wsContactsKeywordMapping``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Defines the transformation between the format returned by the web service and :ref:`contacts_json`.
Response
--------
The response will be considered successful if the HTTP response code is 2xx. All other responses are silently
ignored.
In case the successful response contains ``Last-Modified`` header, the app will remember it and send its value in
the next request in ``If-Modified-Since`` header. The server is expected to return ``304 Not Modified`` if the
contacts have not changed since the last request.
.. important::
It is highly recommended to include the ``Last-Modified`` header in the response and return ``304 Not Modified``
response in case the contacts have not changed. The contacts can be quite big and fully reloading them periodically
(the default period is only 3 minutes!) can consume very significant bandwidth.
Examples
--------
Setup
~~~~~
::
wsContactsUrl = https://example.com/contacts
wsContactsMethod = POST
wsContactsContentType = application/json
wsContactsPostData = {"username" : "%account[username]%","password" : "%account[password]%"}
wsContactsXPath = content/contacts
wsContactsKeywordMapping= firstName=fname,lastName=lname,organization=company,uniqueId=contactId,organizationalUnit=departmentName,lastModified=checksum,extension=contactEntries:tel
request
~~~~~~~
.. code-block:: http
POST /example/contacts HTTP/1.1
Host: example.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
Content-Type: application/json
If-Modified-Since: Wed, 21 Oct 2017 06:28:00 GMT
{"username" : "johndow","password" : "12345"}
response
~~~~~~~~
.. code-block:: http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Content-Length: 3141
Content-Type: application/xml
Last-Modified: Wed, 21 Oct 2017 07:28:00 GMT
0
OK
https://example.com/avatar.png
https://example.com/largeAvatar.png
Jason
Bourne
224
1
d111a2e3-b806-40ce-955b-52c31996a4c7
2018-01-01 16:10:45
2018-01-01 17:20:13
James
Bond
226
3
156eea0b-872f-4e44-844b-ee19c9b3fa46
2018-01-01 16:10:45
2018-03-05 17:22:10
Johny
English
227
4
aa297ca8-5c87-4aa7-825a-5d789cea0b8c
2018-01-01 16:10:45
2018-01-01 17:20:39
Discussion
~~~~~~~~~~
The client has some previous response stored with Last-Modified date of ``Wed, 21 Oct 2017 06:28:00 GMT``. It sends this
value in ``If-Modified-Since`` header of the request.
The server has a newer version of the contacts, by 1 hour. It sends 200 OK response with the new value in
``Last-Modified`` header and XML in the response body. The array of contacts is burried inside the response; the app
will use the ``wsContactsXPath`` to get to the node with contact elements. The app will then enumerate child nodes of
this node and apply the transform described in the next section.
Example JSON response
~~~~~~~~~~~~~~~~~~~~~
In case the web service returns ``Content-Type: application/json``, the response should look like below. In case there is
``wsContactsKeywordMapping`` defined, it will be used.
.. code-block:: json
{
"contacts": [{
"avatar" : "https://example.com/avatar.png",
"largeAvatar" : "https://example.com/largeAvatar.png",
"birthday": "1998-06-14",
"checksum": "DFC1490F899CB9FD",
"city": "Tiburon",
"contactEntries": [{
"entryId": "tel:0",
"label": "home",
"type": "tel",
"uri": "555-610-6679"
},
{
"entryId": "tel:1",
"label": "work",
"type": "tel",
"uri": "+420 276 285 602"
}
],
"contactId": "E94CD15C-7964-4A9B-8AC4-10D7CFB791FD",
"country": "USA",
"countryCode": "us",
"displayName": "David Taylor",
"fname": "David",
"lname": "Taylor",
"notes": "Plays on Cole's Little League Baseball Team",
"state": "CA",
"street": "1747 Steuart Street",
"zip": "949203"
},
{
"avatar" : "https://example.com/avatar2.png",
"largeAvatar" : "https://example.com/largeAvatar2.png",
"birthday": "1977-07-20",
"checksum": "AAC1490F888CB9C9",
"city": "Prague",
"contactEntries": [{
"entryId": "tel:0",
"label": "home",
"type": "tel",
"uri": "555-610-8888"
},
{
"entryId": "tel:1",
"label": "work",
"type": "tel",
"uri": "+40 774 935 236"
}
],
"contactId": "AAAAD15C-7964-4A9B-8AC4-10D7CFB7983C",
"country": "Czech Republic",
"countryCode": "cz",
"displayName": "Josef Novotny",
"fname": "Josef",
"lname": "Novotny",
"notes": "Exists only for the purpose of testing contacts",
"street": "14 Dlouha",
"zip": "11150"
}
]
}
.. _contacts-transformation:
Transformation
--------------
The native format of contacts is described in :ref:`contacts_json`. In case the web service can return this format,
there is nothing else to do. In case it returns XML like above, we need to define a transformation which will map the
xml nodes to Contacts JSON keys.
The transform for the XML above would look like this::
firstName=fname,lastName=lname,organization=company,uniqueId=contactId,organizationalUnit=departmentName,lastModified=checksum,extension=contactEntries:tel
The transformation is a string with comma-separated entries in the form ``xmlNodeName=jsonKey``. In this example, we
use the correct key names for first and last name, company, department and contact identifier. The web service result
provides ``lastModified`` value, which we can use as our internal ``checksum`` (the value will change whenever the contact
data are modified).
This particular XML response uses only one phone number per contact, there is no array of contact entries like in our
internal representation. To deal with situations like this, there is a special syntax used in the last entry.
It tells the app to create a new element in contactEntries JSON array, set the type key to ``tel`` and ``uri`` key to
the value found in ``extension`` xml node. It's also possible to specify a label of the particular entry in ``contactEntries``. For example the following mapping::
extension=contactEntries_ext:tel,workNumber=contactEntries_work:tel,homeNumber=contactEntries_home:tel
will create tree phone numbers with labels ``ext``, ``work`` and ``home`` with values from XML nodes ``extension``, ``workNumber`` and ``homeNumber`` respectively.