.. _quickdial:

==========
Quick Dial
==========

.. contents::
   :local:
   :depth: 3

Overview
========

Quick Dial items show in the Quick Dial panel in Cloud Softphone app. The entries may be added by user and they can
also be provisioned from Cloud Softphone portal and/or directly by provider via :ref:`global-external-provisioning`.

Since both end user and provider can modify the items, conflicts may happen. Cloud Softphone solves the problem using
the concept of merging, as described in :ref:`mergeable-xml`

XML Format
==========

Use the XML format below to provision Quick Dial items:

 .. code-block:: xml

      <quickDial>
        <item id="qd1" priority="50">
            <displayName>Canteen</displayName>
            <uri>5000</uri>
            <portraitUrl>firstContactUrl</portraitUrl> 
        </item>
        <item id="qd2">
            <displayName>Secretary</displayName>
            <uri>1234</uri>
            <portraitUrl>secondContactUrl</portraitUrl> 
        </item>
        <item id="qd3" action="remove"/>
      </quickDial>

The example above contains 3 items:

1. The first item is a new item with ``id="qd1"`` and ``priority="50"``, which is higher than GUI priority. This makes the item non-editable in GUI.
2. The second item is a new item with ``id="qd2"``.
3. The third item is a remove action for item with ``id="qd3"``. This will remove the item from the Quick Dial list.

Removing Quick Dial Items
=========================

To remove obsolete Quick Dial entries, you can either delete specific items by setting the ``action="remove"`` attribute 
on individual items, or remove all items below a certain priority level.

The latter can be achieved by specifying the ``maxQuickDialReplacePriority`` attribute on the root ``<quickDial>`` node.
When this attribute is set, all existing Quick Dial items with a lower priority value are automatically removed.

A common configuration is to use ``maxQuickDialReplacePriority="21"``. This works because Quick Dial items created by 
the user have the implicit *GUI* priority (``40``), while items created through Global External Provisioning have the 
implicit *External Provisioning* priority (``20``). 

For example, consider the following response from Global External Provisioning:

.. code-block:: xml

   <quickDial maxQuickDialReplacePriority="21">
     <item id="qd1">
       <displayName>Canteen</displayName>
       <uri>5000</uri>
       <portraitUrl>firstContactUrl</portraitUrl> 
     </item>
     <item id="qd2">
       <displayName>Secretary</displayName>
       <uri>1234</uri>
       <portraitUrl>secondContactUrl</portraitUrl> 
     </item>
   </quickDial>

Later, if the *Secretary* entry is removed from the provisioned list, it will also be removed automatically from 
the user's Quick Dial panel because its priority is lower than ``21``.