Contents


NOTE: If you are using a FW version lower than 8.7.3, please go to this link for instructions and examples.




Applies to

A number of settings may be described using the here described general xml-syntax. The settings currently (8.7.3) are:

general_purpose_xml_descriptions
fkey
user_event_list_uri
springboard_pkey
action_received_subscr_notify_url
idle_ok_key_action
idle_cancel_key_action
idle_up_key_action
idle_down_key_action
idle_left_key_action
idle_right_key_action
dkey_retrieve
dkey_dnd
dkey_directory
dkey_menu
dkey_transfer
dkey_hold
dkey_record
dkey_conf
dkey_record
dkey_retrieve
dkey_redial
dkey_directory
dkey_menu
dkey_conf
dkey_hold
dkey_settings
dkey_help
dkey_snom
dkey_transfer
dkey_dnd
gui_fkey

Structure

An Xml Description may has the following subtrees:



general

<general type="BusyLampField" identity="1"
  <replaces id="OldBlfId" type="OldBlfType"/>
</general>

The <general> tag is used to define the basic setup of an xml entity. These are the attributes:

  • type the type is used sometimes shown in the PUI, e.g. inside the virtual-key-screen of snom 8xx series. The type is also useful in assign-actions to define which xml-entities to access.
  • translation_key (since 8.9.3.60) assigns a translation for the WUI and PUI to the type. The specified key must exist in both text files.
  • identity links the xml-entity to a certain identity of the phone. E.g. to tie it to the first identity, set this to 1. The association is currently only used when xml sets up a 45633983.

The <replaces> tag (since 8.9.3.83) is optional and is used in replacement plans to indicate the the ID and/or the type have been renamed. When the phone is provisioned with settings using the old replacement plan names these settings will be converted to the new names. There can be multiple <replaces> tags if the plan was renamed multiple times thus conserving the naming history.

  • id identifies the the replacment plan ID that was renamed
  • type identifies an XML definition that has been replaced by what is defined in the replacement plan


initialization

<initialization>
 <state value="initial"/>
 <variable name="subscr_uri" value="sip:424711@com.snom"/>
 <array name="label" separator=" " value="BLF 424711" translate="false"/>
</initialization>

The initialization tree is used to setup variables and the initial state of an xml-entity uppon loading of the xml-configuration. These are the available subtrees:

  • state will set the initial state to the content of it's value-attribute
  • variable will create a dynamic variable by the given name (via name attribute) set to the value provided (via value attribute). The translate attribute defaults to 'false', so is not really necessary in the given example. If translate (since 8.9.3.60) is set to 'true' the content of value is used as a key into the text file.
  • array exists since 8.7.4 and creates a dynamic array whose initial values are those from the value-attribute splitted at the provided separator (must be a single character)


subscription

The subscription tree is used to create a sip-subscription. This is done whenever the setting is read or changed. When the same subscription is defined multiple times in different xml settings the phone will only send out one.

Subscription tags have the the following attributes:

  • type, these values are allowed:
    • presence a subscription of event-type presence will be initiated to the uri defined in the uri-attribute
    • dialog a subscription of event-type dialog will be initiated to the uri defined in the uri-attribute
    • dialog-list a subscription of event-type dialog will be initiated to the uri defined in the uri-attribute. The subscription-request will have the supported-header set to eventlist.
  • for, defines what to subscribe for (will appear as request-uri in the subscription)
  • to, defines where to subscribe to (will appear as to-field in sip-message of the subscription)

Subscription trees have the following subtrees:

  • route the route tag contains in it's body the routing information of where to send the subscription to, eg: <route>sip:blf.server.intern;lr</route>
    • optional, multiple tress possible
    • please always add the lr-parameter

Attribute values and route-tag-content may contain $()-placeholders which allow for insertion of variables and arrays from the xml-entity context. This is only done once when creating the subscription. Changing variables will not cause a updated subscription sip-wise. Essentially one can only use the variables defined in the initialization.



NotifyParsingRules

NotifyParsingRules enclose a set of ParsingRules that are to be matched against received NOTIFY messages.

NotifyParsingRules have these attributes:

  • type: defines what to use the rules for. Its value may be one of the following:
    • applies:
      • when it's parse-result is anything other than an empty string the received notify-xml is identified to be used for the described xml-entity (i.e. for the setting that has this xml description). In this case parsing continues instead of being aborted. Other NotifyParsingRules will only be used when this apply-rule returns a non-empty string.
      • must occur only once
      • mandatory
      • this rule is evaluated before all others
    • state:
      • determines the state (arbitrary string).
        • When used for key descriptions the state will be shown in PUI whenever showing the text representation of the state of the key (8xx virtual key view and 820 side screen). It also defines the LED associated with the key in conjunction with the led-settings (e.g. stk_led_on);
        • The state is also usefull to determine which other NotifyParsingRules (type = "array" or "variable") to use and which actions may apply.
      • must occur only once

      • optional

      • this is the 2nd rule being evaluated (right after apply-rule matches)

    • variable:
      • creates a variable within the context of this xml-entity - variable name is defined by the attribute "id".
      • may occur multiple times
      • optional
      • these rules get evaluated after apply- and optional state-rule, evaluating order is defined by order in the xml
    • array:
      • creates an array within the context of this xml-entity - array name is defined by the attribute "id".
      • the array size is determined by however many element-nodes (xml-tags) the Xpath of the matching ParsingRules points to.
      • may occur multiple times
      • optional
      • these rules get evaluated after apply- and optional state-rule, evaluating order is defined by order in the xml
  • id: defines the name/id of an array or variable.
    • value may be any alphanumeric string, except for these special tokens: state, type, index, value
    • an xml-entity should never have an array and variable of with the same id/name
    • only valid in NotifyParsingRules of type variable and array
  • states: contains multiple states in a coma-separated list-> The NotifyParsingRule will only be parsed when the current state of this xml-entity matches one of those in this list.
    • only valid in NotifyParsingRules of type variable and array


action

The action-tag encloses a set of set of actions of different types.

Though each action type has its own syntax, there are a few common traits:

  • each action-type may occur as often as wanted
  • each action has an attribute named "when" - it defines on which event the action may be done. These values are supported:
    • on press the action will be taken, when the associated key is pressed. This value is only allowed in settings describing a key-behavior.
    • on release the action will be taken, when the associated key is released. This value is only allowed in settings describing a key-behavior.
    • on notify the action will be taken, when an incoming sip-notify is determined to apply to this xml-entity. See NotifyParsingRule of type applies
      • prior to taking any action, all Notify Parsing Rules will be evaluated
      • is default, i.e. will be taken should no when-attribute be set
    • after initialization (since 8.7.4) the action will be taken just after the xml configuration is first loaded/applied.
  • each action has an attribute named states which contains multiple states in a coma-separated list-> The action will only be taken when the current state of the xml-entity matches one of those in this list.
  • all attribute-values of actions may contain $()-placeholders which allow for dynamic insertion of variables and arrays from the xml-entity context

Here are the available action types:

  • assign action

  • invite action (in versions <= 8.7.4.4 named dial)

    • An invite-action will send an invite. It specific attributes are:

    • target which holds the number or sip-uri to be called.

    • replaces (optional), when set inserts the specified replaces-header into the invite thus allowing pickup.

    • request_uri (conditional), when dial action describes a pickup (i.e. has a replaces attribute) the actual request uri for the invite may be specified with this attribute. The target-uri is then only used for the to-header of the invite.

    • hide (optional), boolean, defaults to false, when set to true, resulting call will not have audio nor show up in PUI (starcode).

  • refer action

    • A refer-action will send a sip refer message. It has two attributes:

    • target which holds the sip-uri to refer a call to.

    • source which should hold the id of an active call (the internal id, not sipp call id). When empty, no refer will be send.

  • url action

    • An url-action fires a http-get request to the provided url.<url target="uvw@xyz.org" when="on notify"/>

    • The url action has one specific attribute named target which holds the url to send the http-get-request to.

  • dtmf action (introduced with fw.version 8.7.3.11)

    • A dtmf-action will send an given numbers as DTMF tones. It specific attributes are:

    • target which holds the numbers to be sent.

  • request action (introduced with fw.version 8.7.4.7)

    A request-action will send requests to a module within the phone. It has three attributes:

    • module which names the module to be inquired
    • function says what you want the module to do
    • result_destination holds the name of a variable inside this xml-entity that is to receive the answer to your request. This parameter is optional since not all requests provide a useful answer.

    Some module functions take attributes, use parameter sub-tags to provide them. These parameter tags must contain two attributes:

    • name to provide the name of the parameter
    • value for the value of the parameter

    Your action could e.g. look like this:

     <request when="on press" function="clear" module="CallLists" result_destination="my_local_var">
       <parameter name="list_type" value="dialed"/>
     </request>
    

    The module-request-interface was introduced with 8.7.5. to provide a common interface for all modules to use functionalities of other modules. The list of modules and supported functionality should grow soon, for now we only support this:

    module: CallLists
    functions:
    - name: clear - clear the call lists, either all or the one specifically provided
    - parameters:
       - name: list_type - defines which call list to clear. When it's not provided or contains an invalid value: all call lists will be cleared
       - valid values: Missed, Dialed, Received , Parked
    - returns: OK (always)
    - fw-version: 
       - 8.7.5 as described above
       - 8.7.4.7: faked module-interface: only accessible by xml-configurations and without a return value


Special variables/arrays

Variables can be set through various ways ( actions , 45633983 or in the 45633983). Some variables and arrays have a special meaning.

Label

With dynamic labels it is possible to show a text for the function keys that have a corresponding dynamic display (for example, on D385 phones). This can be done using variables label or ui_label. Both variables can be used for the same purpose. If both variables are set, ui_label has priority.

The dynamic label can also be seen in the web interface in the Function Keys section under XML Label:

The following example will set the button label to the text "Clock" during initialization:

<variable name="label" value="Clock"/>

The next example will change the label to "Clock off" when the button is pressed if the current state is on:

<assign when="on press" states="on">
   <source value="Clock off"/>
   <destination id="label"/>
</assign>

Icon

With XML definition it is also possible to show an icon, for the function keys that have a corresponding dynamic display (for example, D385 or D735 phones). This can be done using the icon variable.

The value of the icon variable can be:
-the name of an existing phone icon. You can find the existing phone icons here: fkey_icons (the name to use in the value can be copied from column Icon Type, for example: kIconTypeFkeySaveContact)
-or an HTTP/S link to your custom icon, for example https://service.snom.com/download/attachments/36831457/room_service.png

Examples of setting the icon during initialization:

<variable name="icon" value="https://service.snom.com/download/attachments/36831457/room_service.png"/>

<variable name="icon" value="kIconTypeFkeySaveContact"/>

Examples of setting the icon using assign:

<assign when="on press">
   <source value="kIconTypeFkeySaveContact"/>
   <destination id="icon"/>
</assign>

<assign when="on press">
   <source value="https://service.snom.com/download/attachments/36831457/room_service.png"/>
   <destination id="icon"/>
</assign>