Global External Provisioning

Global External Provisioning is an optional web service implemented by the provider. It can be used to provision data which are not part of the Account XML. Global External Provisioning receives all input-parameters-for-provisioning, so the response can vary for individual users.

Currently, this web service allows provisioning of Quick Dial entries and Custom Dial Actions.

Web Service Definition

The web service is configured at Cloud Softphone portal. It uses the standard Web Service Definition syntax with prefix initialGlobalProvisioning, i.e. initialGlobalProvisioningUrl 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. 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>

In case of successfull response, the returned XML should have a root node, whose name is not important - we’ll use root in our examples. Inside the root node, there may sub-nodes with provisioning data. As of the moment of writing this documentation, subnodes quickDial and dialActions are supported.

See articles about Dial Actions and Quick Dial for details about XML format.

Example of successful external provisioning

request:

GET /globextprov?cloud_username=johndow&cloud_password=12345678&cloud_id=EXAMPLE HTTP/1.1
Host: provider.com
Connection: close
Cache-Control: max-age=0
User-Agent: CloudSoftphone/1.6.4

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

<root>
  <dialActions>
    <dialAction id="id3">
        <displayName>Recorded call</displayName>
        <rewriting>
            <rule>
                <actions>
                    <action type="overrideDialAction" param="voiceCall"/>
                    <action type="continue"/>
                </actions>
            </rule>
            <rule>
                <conditions>
                    <condition type="doesntStartWith" param="00"/>
                    <condition type="startsWith" param="0"/>
                </conditions>
                <actions>
                    <action type="recordCall"/>
                </actions>
            </rule>
        </rewriting>
    </dialAction>
  </dialActions>

  <quickDial>
    <item id="qd1">
        <displayName>Canteen</displayName>
        <uri>5000</uri>
    </item>
  </quickDial>
</root>

The example above provisions a new Dial Action which, when used, will dial the number as voiceCall and if the number starts with single zero, it turns on recording automatically. It also provisons one quickDial item.

Re-provisioning

Global external provisioning may also be called at regular intervals to refresh global external provisionig. There is a separate web service definition for re-provisioning, configured at Cloud Softpohne portal. The syntax follows the Web Service Definition syntax with prefix globalExtProv and is stored in prefKeys. The refresh period is stored in globalExtProvRefresh prefKey in seconds, the default is 3600 (one hour).

All re-provisioning is fully automated and transparent for end users, they are not prompted or notified about the change.