.. _global-external-provisioning:

============================
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 :ref:`account-xml`. Global External Provisioning receives all
:ref:`input-params-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 :ref:`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:

 .. code-block:: xml

  <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 :ref:`dialactions` and :ref:`quickdial` for details about XML format.

Example of successful external provisioning
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

request:

 .. code-block:: http

    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:

 .. code-block:: http

    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
:ref:`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.