Content
This document explains the structure of an XML Definition.
<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:
type identifies an XML definition that has been replaced by what is defined in the replacement plan
<general type="BusyLampField" identity="1" <replaces id="OldBlfId" type="OldBlfType"/> </general>
<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:
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:
route - the route tag contains in its body the routing information of where to send the subscription to, for example:
<route>sip:blf.server.intern;lr</route>
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 enclose a set of ParsingRules that are to be matched against received NOTIFY messages.
NotifyParsingRules have the following attributes:
must occur only once
optional
this is the 2nd rule being evaluated (right after the apply-rule matches)
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:
on change (since 10.1.87.0) the action will be taken when the value of a monitored variable changes.
<assign when="on change" context="identity.1" id="phone_status" value_in="Alerting,In_A_Call"> <assign when="on change" context="identity.1" id="phone_status" value_not_in="Alerting;Forwarded" separator=";">
<reference name="phonstat" module="identity.1" id="phone_status"/> ... <assign when="on change" reference="phonstat">
The variable to monitor is specified using either the parameters context and id (see below) or (since 10.1.90.0) the reference parameter (see above).
The optional parameters value_in, value_not_in limit the firing of the event to when the monitored variable assumes a value either in or not in the given list. Values are separated be default with a comma, a different single character may be specified using the optional parameter separator.
Below are the available action types.
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.
The source tag can have the following attributes:
$()
notation.separator (since 8.7.4) is optional but may only be used together with value - it must be a single character which is used to split up the value into an array. The following example will create an array with the 3 elements right, left and center.:
<source context="local" value="right center left" separator=" "/>
The destination tag can have the following attributes:
Both source and destination can use the following attributes:
One XML entity context is tied to each setting that may be described using XML Definitions. You may define variables and arrays as you want and place whatever you want inside the context. There are however a couple of reserved keywords that look like variables but are actually handled differently internally, please never use them when defining variables:
state: the state the entity is in, the string may be whatever you want it to
type: an arbitrary string set during configuration, it never changes unless the setting gets a new configuration provisioned.
id: and unique identifier for the entity (example: LineKey.0)
index: within assign-actions that have an array as source, the index gets set within a loop while assigning each array-member to its destination.
There are also a number of special variables and arrays you may access like any other variable but that get special treatment in the PUI.
module_name - get or set value from a module.
Here is an example of taking the translation for the word "off" and putting it into the label variable:
<assign when="on press" states="on"> <source context="language" id="off"/> <destination id="label"/> </assign>
The call contexts are used to obtain information from ongoing calls. The following variables can be read/accessed:
state: the state the call is in (Note that states are case sensitive: connected, ringing, on_hold, holding, closed, offhook, calling or ringback)
id: is an internal unique identifier for a call (value is: id).
preping_for_transfer: boolean, set to true when the referred call is in the process of being transferred, i.e. while the user is selecting a transfer target for it.
The identity contexts are used to obtain information about the identities on the phone. The following variables can be read/accessed (changing variables of identities is not supported):
state: the registration state of the identity (registered, registering, failed or inactive)
id: and unique identifier, a number between 1 and 12, that identifies the referred identity
missed_count: an integer count of the number of missed calls
display_name: access to setting user_realname
idle_name: access to setting user_idle_text
user_name: access to setting user_name
user_host: access to setting user_host
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.
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>
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:
join - is used in combination with multiple source-trees and an attribute named "pattern". Use this function to combine the different source-values before assignment.
The pattern-attribute 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 on.
If the sources are arrays then the array-size of the last source determines how many joined values there will be (best make all arrays be of the same size). The first array members of all sources are then joined as described by the pattern before forming the first joined value. The second array members form the second value and so forth.
<assign when='on release' states='idle'> <source context="this entity" id="A_num"/> <function name="join" pattern="Calling A: $(src0)"/> <destination context="this entity" id="label"/> </assign> <assign when='on release' states='in_a_call'> <source context="this entity" id="A_num"/> <source context="this entity" id="B_num"/> <function name="join" pattern="$(src0) busy, calling $(src1)"/> <destination context="this entity" id="label"/> </assign>
find_index - is used to determine the index of the source-value(s) of the first source-tree within the array given in the second source-tree. The result is an array of values by the size of the first source-tree. Should a value not be inside the array of the second source-tree, then the value will be left empty in the result.
<assign when="on notify" states="partial"> <source context="this entity" id="uris[]"/> <source context="this entity" id="full_uris[]"/> <function name="find_index"/> <destination context="this entity" id="full_idx[]"/> </assign>
substring (since 10.1.90.0) - is used to extract a substring from the source value. It requires a single source. It takes to argument attributes pos (start of substring) and count (length of substring). pos default to "0" and count to the remaining length of the string. One of the attributes must be set.
<assign when="on notify" states="ringing"> <source value="$(ring_id)"/> <function name="substring" pos="5"/> <destination context="this entity" id="pickup_num"/> </assign>
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>
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.
<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>
An invite-action will send a SIP INVITE. Its 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 the INVITE action describes a call 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, the resulting call will not have audio nor show up in PUI (for example this can be useful when calling a starcode)
in versions <= 8.7.4.4 this action was named dial
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 the SIP call id). When empty, no refer will be send.
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>
An url-action fires a http-get request to the provided url.
The url action has one specific attribute named target which holds the url to send the http-get request to.
<url target="http://myexample.com/test.xml" when="on notify"/>
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:
target which holds the digits/tones to be sent.
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.
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 .
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.
The following variables have a special meaning:
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.
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>
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>
Further Information
Related articles