.. _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.