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 Input Parameters for Provisioning, including username and password. The response of external provisioning web service is 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 Web Service Definition syntax with
%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
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:
<error> <message>Custom error message comes here</message> </error>
The XML subtree under the
account node should contain the Account XML which will be merged into the app
Example of successful external provisioning¶
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
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 <account> <username>B63349F4EE</username> <password>45F4BF5F0E191F5DCC27</password> <allowMessage>0</allowMessage> <X-install-id>AD4535EF902BB13</X-install-id> </account>
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.
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
allowMessagewith value 0, which disables messaging for this particular user.
3. custom account parameters¶
Note the XML node
X-install-idin the example response. This is not any known 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
initialScreenparameter 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
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 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
Web Service Definition syntax with prefix
extProvUrl etc. By default, it uses GET method
%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
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.
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.