Cloud Softphone Provisioning

Overview

When Cloud Softphone apps are started for the first time after installation, they need to be provisioned with graphics theme, configuration data, account credentials and parameters.

Input Parameters for Provisioning

The provisioning has three input parameters: cloud ID, username, password. These parameters fully determine how the app will be provisioned and may be passed into the application in several different ways, described below. Some of the parameters may be left empty.

cloud ID is the unique identifier of your app. You choose this identifier on Cloud Softphone web portal in the very first step when creating a new app.

Note

You can have access to at most two versions of your app on Cloud Softphone web portal: One “live”, production version and one “editable” version, which you get by making a copy of the production one. You can make changes there and experiment with various settings without affecting the production version.

When provisioning the app, the “editable” version is addressed by adding a “*” character after the cloud_id parameter.

Input fields

The initial screen of Cloud Softphone app typically has two input fields. One is titled “Cloud ID”, the other one “Password”.

The text from first input field is processed by finding the last ‘@’ character from the end of the string and splitting the string in two from this position. The first part is treated as username, the second part as cloud ID.

The content of the “Password” field is taken as password.

Warning

The fields are url-decoded before use. Searching for the ‘@’ character from the end of the string helps in some cases when the username has ‘@’ sign in it, but the correct input must have the part before “@CODE” url-encoded.

Examples:

input username cloud ID note
CODE (empty) CODE empty username
user@CODE user CODE  
user@CODE* user CODE* specifies test version of the app
someone@server.com@CODE someone@server.com CODE gracefully accepted
someone%40server.com@CODE someone@server.com CODE correct form

QR Code

The parameters may be passed via QR code. There is an embedded QR code reader in the app which can be used to scan the code.

The code should contain text in the following format:

csc:username:password@CODE
csc
URI scheme prefix - required as-is
username
this part will be used as username parameter
password
this part will be used as password parameter
CODE
this part will be used as cloud ID parameter

Warning

Like above, the fields username and password should be url-encoded. Valid Cloud IDs contain only letters and digits, so url-encoding should have no effect on it.

Examples:

input username password cloud ID
csc:CODE (empty) (empty) CODE
csc:user:12345@CODE user 12345 CODE
csc:someone%40server.com:%40%41%42@CODE someone@server.com @AB CODE

White-label App Specifics

In case you have a full white-label app, the cloud ID parameter is hard-coded in your app. This changes input parameter processing in the following way:

  • the hard-coded cloud_id parameter is always used. If the user specifies a different cloud ID parameter, it is discarded and silently replaced by the hard-coded cloud ID.

  • the “*” character is preserved. If the hardcoded cloud ID is “X” and the user specifies “Y*”, the value which will be used is “X*”

  • in case user enters a single word into the first input field, it’s normally taken as cloud ID, as described above. If hard-coded cloud ID exists, this behavior is modified and the single word is considered a username.

    Example:

    Hard-coded cloud ID is “X”. User enters “ABC” into the first field and “1234” into the second field. The resulting input parameters are:

    cloud ID X
    username ABC
    password 1234

Step 1: Graphics theme provisioning

The graphics theme is downloaded from Cloud Softphone web portal. This process takes the cloud ID input parameter and also mobile platform and screen resolution, which are detected automatically by the mobile apps. username and password fields play no role here.

A compact ZIP file with all graphics assets is downloaded and unpacked.

Step 2: Configuration provisioning

In this step, the mobile app configuration and SIP account credentials and are downloaded from various sources and completed together. This process is quite complex, we will describe the cases with and without external provisioning separately.

No external provisioning

In this simple case, the mobile app will request configuration from Cloud Softphone web portal. This request passes the cloud ID parameter and target platform type (iOS, Android, …) to the portal. The web portal sends information about app configuration (enabled features, codecs, add-ons etc.) and also SIP account parameters, specified in Account XML format.

When downloaded, the mobile app takes the username and password parameters and inserts them into the received Account XML. This should complete the SIP account specification and the account is saved and can be used immediately.

In case at least one of the username or password parameters were empty, the account doesn’t pass validation and can’t be saved. In this case, the user will be shown the “new account” form, where he can enter the username/password manually.

Note

The form is pre-filled with all parameters which are available. For example, if only username was specified in QR code, the username field will be pre-filled and user will only have to type the password.

External provisioning

In case external provisioning is enabled, it’s executed as the first step of the whole provisioning process.

External provisioning uses a web service, which is configured in “Provisioning options” step in Cloud Softphone web portal. If you configure your external provisioning url as:

the web service is called as follows:

https://provider.com/prov/?cloud_username=%username%&cloud_password=%password%&cloud_id=%fullcode%&initialScreen=1

The placeholders %username%, %password% and %fullcode% will be replaced by the username, password and cloud ID parameters from the initial screen. The last parameter initialScreen indicates whether the script is called from the initial app screen as new account provisioning, or if it is re-provisioning (described later).

The web service is expected to return 2xx OK HTTP response with Account XML in the body. 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>

When external provisioning is successful, the provisioning process continues by downloading the general configuration parameters from Cloud Softphone web portal, as described in chapter No external provisioning. The Account XML from external provisioning is then merged with the one returned from Cloud Softphone web portal.

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-Encoding: gzip
Content-Length: 183
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive
Content-Type: text/xml

<account>
  <cloud_username>johndoe</cloud_username>
  <cloud_password>12345678</cloud_password>
  <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 a valid 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

The mobile apps check Cloud Softphone web portal for new version of app settings and graphics theme every time they are started and also periodically. The period between checks is 1 hour.

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

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. As soon as the user closes Settings, the changes are applied.