Cloud Softphone Provisioning¶
- Input Parameters for Provisioning
- Step 1: Graphics theme provisioning
- Step 2: Configuration provisioning
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.
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.
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.
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.
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.
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:
- URI scheme prefix - required as-is
- this part will be used as username parameter
- this part will be used as password parameter
- this part will be used as cloud ID parameter
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.
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 email@example.com @AB CODE
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.
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
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.
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.
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.
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.
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:
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.
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-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>
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 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]%
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.
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.
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. As soon as the user closes Settings, the changes are applied.