This document explains the structure of an XML Definition.


general 

<general type="Example"/>

The <general> tag is used to define the basic setup of an XML entity. The <general> tag has the following attributes:

The <replaces> sub-tag (since 8.9.3.83) is optional and is used in replacement plans to indicate that 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. The <replaces> sub-tag has the following attributes:


initialization 

<initialization>
  <state value="initial"/>
  <variable name="subscr_uri" value="sip:424711@com.snom"/>
  <array name="my_array" separator=" " value="BLF 424711" translate="false"/>
  <identity value="1"/>
  <reference name="uuid" module="setting" id="user_uid[1]"/>
</initialization>

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

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 following attributes:

Subscription trees have the following subtree:

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 the variables will not cause an updated subscription from the SIP point of view. 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 the following attributes:

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:

Below are the available action types.


assign action

An assign-action can be used to change the state of an XML entity or to assign values to its variables or arrays.

An assign-action tree contain at least two sub-tags: source and destination.

Source sub-tag

The source tag can have the following attributes:

Destination sub-tag

The destination tag can have the following attributes:

Sub-tag attributes

Both source and destination can use the following attributes:

When an assignment action fires, it first collects all the described source values and after that all destination contexts. If there is only one source value, it will be assigned to all found destinations. When there are multiple source values an assign-loop gets started assigning the first found source-value to the first destination-context. Next, both lists get reduced by the just used element and the loop continues. The end is reached when either list is empty. When the source is an array, then for each loop the index-variable gets set (starting with 0). If a destination-requirement uses this index, this requirement gets re-evaluated on each loop.


Joining multiple sources into one destination

This section is only available in versions >= 8.7.4.6 and < 8.7.5.3 .

Starting with fw.version 8.7.4.6 the source-tags may occur multiple times. This is used in combination with the newly introduced sub-tree "join" which will hold the description on how to join the different source-values before assigning them to the destination.

The join-tag has one attribute named "value" which holds a string with place-holders, e.g.: "A: $(src0) - B: $(src1)". The "$(src0)" will be replaced by the value referred to by the first source-tag, "$(src1)" by that of the 2nd source-tag and so forth. With version 8.7.5.3 this sub-tree was replaced by the function-sub-tree described below.

 <assign when="on notify">
   <source context="this entity" id="name"/>
   <source context="this entity" id="number"/>
   <join value="$(src0) (Tel: $(src1))"/>
   <destination context="this entity" id="label"/>
 </assign>

As of 10.1.87.0 this can also be achieved with a simplified syntax:

 <assign when="on notify">
   <source value="$(name) (Tel: $(number))"/>
   <destination context="this entity" id="label"/>
 </assign>

This simplified syntax may also be used for external variables if a reference is defined first:

<initialization>
  <reference name="ringnum" module="identity.1" id="ringing_number"/>
</initialization>
<action>
  <assign when="on change" context="identity.1" id="phone_status" value_in="Alerting">
    <source value="Ring-$(ringnum)"/>
    <destination context="this entity" id="person_id"/>
  </assign>
</action>


The function sub-tree

With version 8.7.5.3 a sub-tree named "function" was introduced. It describes how the source-values get processed before they are assigned to the destination. This sub-tree must have at least one attribute called "name" which names the function. More attributes may be needed depending on the function. The following function names are available:


type attribute

Since 8.7.4 an assign-action may have an attribute named type whose only valid content (for now) is update on change. This tries to always update the destination when the source changes.

In 8.7.4 this only works when the source is a state. Since 8.7.5 you may also register to changes in type, variables and arrays.

Before 8.7.5.1 auto-assign does not work when the source context is set to this entity or language. Since 8.7.5.3 it works for all contexts including this entity and language.

When the action is first fired the linkage to the source is created. There is no way as of yet to undo this linkage. Once the linkage is created, the destination always changes when the source-state changes, the states and when conditions in the action-tag will be ignored in these auto-updates.

 <assign type="update on change" when="after initialization">
   <source context="identity" id="state" require1="${id}==$(identity)"/>
   <destination context="this entity" id="state"/>
 </assign>


default attribute

Since 8.7.5.3 it is possible to define a default value that the destination gets assigned should there be no source-value. This only works when the destination does not depend on the index of the source. I.e. don't use $(index) in destination requirements.


Examples

 <assign when="on notify">
   <source context="this entity" id="cids"/>
   <destination context="all xml entities" id="ResourceCid" require1="${type}==ResourceListBuddy" require2="${BuddyUri}==$(uris[$(index)])"/>
 </assign>

 <assign when="on notify">
   <source context="this entity" id="call_me_uri" value_match=".*ext=(.*)" value_replace="*97$1"/>
   <destination context="this entity" id="pick_up_tel"/>
 </assign>

 <assign when="on notify">
  <source context="this entity" value="right center left" separator=" "/>
  <destination context="this entity" id="label_align[]"/>
 </assign>

 <assign when='on notify' states='ringing'>
   <source context='language' id='linestate_ringing'/>
   <destination context='this entity' id='label'/>
 </assign>

 <assign when='on press'>
   <source context='call' id='id' require='${preping_for_transfer}'/> 
   <destination context='local' id='transfer_id'/>
 </assign>

 <assign when="on change" context="identity.1" id="phone_status" value_in="Alerting">
   <source value="Ring-$(ringnum)"/>
   <destination context="this entity" id="person_id"/>
 </assign>


invite action

in versions <= 8.7.4.4 this action was named dial

An invite-action will send a SIP INVITE. Its specific attributes are:


refer action

A refer-action will send a SIP REFER message. It has two attributes:

publish action

A publish action will send a SIP PUBLISH request (since 10.1.87.0). It has the following attributes:

The publish action requires a body subtag which has these parameters:

Substitutions within the content of the body subtree are possible using the $() notation.

  <publish when="on change" context="identity.1" id="phone_status" target="$(user)" expires="3600">
    <body content_type="application/pidf+xml" event="presence">
      <presence xmlns="urn:ietf:params:xml:ns:pidf" mlns:dm="urn:ietf:params:xml:ns:pidf:data-model" xmlns:rpid="urn:ietf:params:xml:ns:pidf:rpid" entity="$(user)">
        <tuple xmlns="urn:ietf:params:xml:ns:pidf" id="$(uuid)-$(identity)">
          <status xmlns="urn:ietf:params:xml:ns:pidf">
            <basic>$(basic_state)</basic>
            <note>$(presence_state)</note>
          </status>
          <dm:person id="$(person_id)">
            <rpid:activities>$(activity)</rpid:activities>
            <dm:note>$(presence_state)</dm:note>
          </dm:person>
        </tuple>
      </presence>
    </body>
  </publish>


url action

dtmf action

This action was introduced with fw. version 8.7.3.11.

A dtmf-action will send an given numbers as DTMF tones. It specific attribute is:

request action

This action was introduced with fw. version 8.7.4.7.

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

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

A request action could for example look like this: (to start a conference between local identity 2 and remote numbers 100 and 102)

<request when="on press" function="ad_hoc_conference" module="CallInterface" result_destination="my_var">
  <parameter name="identity" value="2"/>
  <parameter name="remote1" value="100"/>
  <parameter name="remote2" value="102"/>
</request>

The module-request-interface was introduced with version 8.7.5. to provide a common interface for all modules to use functionalities of other modules. The currently available list of modules can be found here.

Order of execution

When writing complex XML Definitions it is important to understand the order of execution for the actions on different events. For details please see Order of execution for XML Definition actions .

Setting a variable

As explained above, XML Definitions support custom variables which can be set through various ways: actions , NotifyParsingRules, in the initialization or from the XML Minibrowser.

Special variables

The following variables have a special meaning:

state

The state of an XML definition is a special variable and is used for many purposes. For example, it can be used to change the LED behavior, its content can be a condition for performing actions, etc.


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 definitions it is also possible to show an icon, for the function keys that have a corresponding dynamic display (for example, D385 phones). This can be done using the icon variable.

The value of the icon variable can be:


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


<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>