.. _external-provisioning:
=====================
External Provisioning
=====================
External provisioning is an optional web service which is executed after the app downloads basic app provisioning from
Cloud Softphone portal. The web service is implemented by the provider and receives all
:ref:`input-params-for-provisioning`, including **username** and **password**. The response of external provisioning
web service is :ref:`account-xml` which is merged with provisioning from Cloud Softphone portal.
External provisioning lets the provider to alter app configuration for individual users. It is also used as the last
step of Registration Wizard which verifies PIN code and provides SIP account credentials for user. See the paragraph
about Use Cases below for details.
Web Service Definition
======================
The web service is configured at Cloud Softphone portal. It uses the standard :ref:`web-service-definition` syntax with
prefix ``InitialProvisioning``, i.e. ``InitialProvisioningUrl`` etc.
The placeholders ``%username%``, ``%password%`` and ``%fullcode%`` will be replaced by the **username**, **password**
and **cloud ID** parameters from the initial screen.
Web Service Response
====================
The web service is expected to return ``2xx OK`` HTTP response with ``account`` XML node in the body. Content-Type
should be ``application/xml``. In case the response code is not ``2xx OK``, the provisioning process stops and a
generic error message is shown. To show a custom error message, it's possible to return ``non-2xx`` response code and
put the error message into the response, like this:
.. code-block:: xml
Custom error message comes here
The XML subtree under the ``account`` node should contain the :ref:`account-xml` which will be merged into the app
provisioning.
Example of successful external provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
request:
.. code-block:: http
GET /prov?cloud_username=johndow&cloud_password=12345678&cloud_id=EXAMPLE&initialScreen=1 HTTP/1.1
Host: provider.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.5.6
response:
.. code-block:: http
HTTP/1.1 200 OK
Date: Sun, 15 Mar 2015 00:46:17 GMT
Server: Apache/2.4.7 (Ubuntu)
Vary: Accept-Encoding
Content-Length: 183
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml
B63349F4EE
45F4BF5F0E191F5DCC27
0
AD4535EF902BB13
Use cases for external provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
External provisioning gives providers more control over the provisioning process. Below are some typical use cases when
external provisioning is useful.
1. hidden SIP username/password
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In case end users have some general accounts at the provider and are identified by email address or
some other identifier different from SIP username, external provisioning allows end users to use this identifier,
eliminating the need to give the user another username/password used for SIP.
In the example above, the provider had an end user with login/password ``johndoe/12345678``. Internally, the provider
assigned SIP credentials ``B63349F4EE/45F4BF5F0E191F5DCC27`` to that user. When this user enters his username/password
to Cloud Softphone initial screen, the external provisioning script is called in provider's backend.
This script will find user johndoe, verify the password and find out that this user has SIP service enabled, with
SIP credentials ``B63349F4EE/45F4BF5F0E191F5DCC27``. These credentials are then returned in response.
Note that in this case, the SIP credentials may be completely hidden from end user.
2. per-user configuration
^^^^^^^^^^^^^^^^^^^^^^^^^
External provisioning can be used to set up accounts which are tailor-made for the specific user. In the example
above, let's say the Cloud ID “EXAMPLE” has messaging support enabled. When provisioning user “johndoe”, the script
added node ``allowMessage`` with value 0, which disables messaging for this particular user.
3. custom account parameters
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Note the XML node ``X-install-id`` in the example response. This is not any known :ref:`account-xml` identifier so
it won't be used in SIP account setup. The script detected that a new mobile app is being provisioned by the
``initialScreen`` parameter and assigned this mobile app an auto-generated tracking identifier. This identifier
will be stored persistently in account XML and can be later passed to other web services, addressed as
``%account[X-install-id]%``
Re-provisioning
===============
In case external provisioning is used, the script MAY also be called by the mobile app each time the app is started and
periodically. The period in seconds is specified by ``extProvInterval`` parameter in :ref:`account-xml`. In case this
parameter is not present, the default of 0 will be used, which means "no re-provisioning".
Re-provisioning web service is configured at Cloud Softphone portal and also follows the standard
:ref:`web-service-definition` syntax with prefix ``extProv``, i.e. ``extProvUrl`` etc. By default, it uses GET method
with URL
::
{PROV_HOST}?cloud_username=%account[cloud_username]%&cloud_password=%account[cloud_password]%&cloud_id=%fullcode%&initialScreen=0
The placeholders ``%account[cloud_username]%`` and ``%account[cloud_password]%`` are replaced by the username and
password as they were entered in initial screen, ``%fullcode%`` will be replaced by **cloud ID** of the app and the last
part is to indicate that this request is a re-provisioning and not initial provisioning.
The mobile apps will send ``If-Modified-Since`` header in request and will handle response ``304 Not Modified``. In case
``200 OK`` response is received with new Account XML in response body, the changes will be applied and the account
refreshed.
.. warning::
The default value for ``extProvInterval`` is 0, which means that external re-provisioning will be called only when
creating or editing account. To enable periodical automatic re-provisioning, specify non-zero value of
``extProvInterval`` in your Account XML.
All re-provisioning is fully automated and transparent for end users, they are not prompted or notified about the change.
In case of graphics change, the mobile app is redrawn on-fly using the latest graphics theme.
.. note::
To avoid conflicts, the account is not modified when Settings page of the mobile app is open, or if there is a call
in progress. As soon as the user closes Settings and/or all calls end, the changes are applied.