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 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 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:

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

Example of successful external provisioning

request:

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:

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.

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