Snom Service Hub

Content

Page tree

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:

  • type the type is a title for the XML definition, sometimes shown as label for the key. 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. For example to tie it to the first identity, set this to 1. The association is currently only used when XML definition sets up a subscription.

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:

  • id identifies the the replacement plan ID that was renamed

  • type identifies an XML definition that has been replaced by what is defined in the replacement plan

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


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:

  • state will set the initial state to the content of its 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 above 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 by the provided separator (must be a single character)
  • identity defines which identity is to be used. This parameter is not mandatory.
  • reference (since 10.1.87.0) is like a read-only variable; it points to a variable (id attribute) accessible via the Variable/Array Interface of the specified module attribute; it can be accessed in the XML like a variable as $(name). Note that wildcards are not allowed in the module name, and if id identifies an array element it must include the index in square brackets; it is not possible to read the whole array.

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:

  • type - the following 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.
    • ua-profile - a subscription of event-type ua-profile;profile-type=user will be initiated to the URI defined in the uri-attribute.
    • message-summary - a subscription of event-type message-summary to subscribe for messages
  • 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 the SIP message of the subscription)

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

  • type: defines what to use the rules for. Its value may be one of the following:
    • applies:
      • when its 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)

      • must occur only once

      • optional

      • this is the 2nd rule being evaluated (right after the 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, the evaluating order is defined by the 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, the evaluating order is defined by the order in the XML
  • id: defines the name/id of an array or variable.
    • value may be any alphanumeric string, except for the following special tokens: state, type, index, value
    • an XML entity should never have an array and variable with the same id/name
    • only valid in NotifyParsingRules of type variable and array
  • states: contains multiple strings in a coma-separated list. The NotifyParsingRule will only be parsed when the current state of this XML entity matches one of the strings in this list.
    • only valid in NotifyParsingRules of type variable and array
  • state: contains a string. The NotifyParsingRule will only be parsed when the current state of this XML entity matches the given string.
    • 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 will be executed. The following 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.

    • on change (since 10.1.87.0) the action will be taken when the value of a monitored variable changes. Starting with 10.1.174.0 you can name multiple variables in the same context via numbered id attributes (id0="a" id1="b" id2="c"....)

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

  • 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.
  • each action has an attribute named state which contains one state. The action will only be taken when the current state of the XML entity matches the given state.
  • most attribute-values belonging to an action may contain $()-placeholders which allow for dynamic insertion of variables and arrays from the XML entity context

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:

  • context -> see below
  • require -> see below
  • id is conditional, when not set the source-tag needs an value-attribute
    • when it's set to "state": the source will be the state of an XML entity, otherwise it will either be an array or variable with that name.
    • until 8.7.3 the differentiation between array and variable was done at runtime: if an array existed by that name, it was used as source, else it was assumed to name a variable
    • since 8.7.4 array must be referred to using [], e.g. id="foo" names a variable, id="bar[]" an array
    • since 8.7.4 it is also possible to access single array-members by providing the index. E.g.: id="bar[42]" (starts with index 0).
  • value is conditional, when the value is not used the source-tag needs an id-attribute
    • until 8.7.3 the value was a single fixed string
    • since 8.7.4 it is also possible to provide an array of fixed values using the optional attribute separator
    • since 10.1.87.0 substitutions are possible using the $() 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=" "/>
  • value_match (optional) reduces the source-values to those matching the herein described regular expression.
  • value_replace can only be used when value_match is set. It holds a substitution string that the value will be replaced by before it's assigned to a destination. The regex-groups from value_match may be inserted using $0..n notation.

Destination sub-tag

The destination tag can have the following attributes:

  • context -> see below
  • require -> see below
  • id is mandatory. When it's set to "state": the destination will be the state of an XML entity, else:
    • until 8.7.3: names a variable (never an array). Should no variable of that name exist, it will be created.
    • since 8.7.4: names either a variable, an array or or an array member, distinguished by the postfix, e.g.: a_variable, an_array[], an_array_member[7]. Should the destination not exist, it will be created

Sub-tag attributes

Both source and destination can use the following attributes:

  • context defines where a variable can be found.

    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.

    The context can be set to the following values:
    • this entity (since 8.7.4, was formerly named local):
      • the variable is part of this XML entity
      • default, when no context is provided then it is set to this entity
    • all xml entities (since 8.7.4, was formerly named all)
    • setting (since 8.7.4.5)
      • the Source is a setting
        The setting context allows to read settings. The individual settings are saved as variables and arrays in the setting-context, you can access them via the id-attribute.

    • module_name - get or set value from a module.

       

    • language (since 8.7.4):
      • the Source (not valid in destinations) refers to a translation. For example, you can use the language context to extract a label translation from the Snom PUI language file. The translation is done using the same language map that the PUI is set to use.
        A complete list of translation labels can be found under Firmware Update Center . Here is how you can use them:
        • Open the Firmware Update Center
        • Click on the firmware version that your phone is running
        • Download the Customization File for your model
        • Extract the archive
        • Browse to the languages directory
        • Open one of the gui_lang_... files, either gui_lang_EN.xml or the one for your language you prefer
        • Search in the file for the text that you wish to replace
        • Take the value under n="...", and remove the "lang_" part at the beginning. The resulting text is the value that you can then enter in the id attribute in order to use this translation.
        • For example, the labels for text "on" and "off" for the German language:

        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>
    • call (since 8.7.4):
      • the Source (not valid in destinations yet) refers to all calls currently present on the phone

        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.

    • identity (since 8.7.4):
      • the Source (not valid in destinations yet) refers to all of those up to 12 identities that can be registered on the phone

        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

        • phone_status: (since 10.1.87.0) the current phone (not user!) presence status. This status is determined by the phone automatically. Possible values:
          • Offline the identity is not registered
          • Available the identity is registered and the phone is able to accept calls
          • Alerting there is an unanswered incoming call
          • In_A_Call the phone is off-hook or in a call (includes holding)
          • Dnd_All Do Not Disturb is active
          • Forwarded unconditional call forwarding is active
        • ringing_number: (since 10.1.87.0) The currently ringing number (incoming). If there is more than one it is the latest one.

        • 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

  • id defines the name of an array or variable, or when ="state" says that the Source or Destination is the state of the referred context. This attribute is evaluated differently when found in the Source or Destination tags, please see the detailed description of these tags above for more information.
  • require reduces the number of context-entities from/to which the variables are read/set. It consists of a comparison sign and two operands on either side. Each operand consists of alphanumeric constant characters and placeholders for dynamic variable insertion. The placeholders start with a $-sign followed by a pair of brackets enclosing the variable name. Curly brackets are used for inserting the variables of all the contexts currently referred to (i.e. all the contexts named via the context-attribute) while parentheses are used for the local XML entity context. The variables may actually be variables but may also insert array-members or the state or type of an XML entity. You can have an arbitrary amount of require attributes as long as the name starts with 'require' and all requirements have to be met for this source of destination to be used. There are 2 special options that allow you to add or subtract values via $+(a,b) and $-(a,b). Each xml module including the xml definitions has access to its own id (short and full) via $(id) and $(module_id). See the following examples for more clarity:
    • ${type}==ResourceListBuddy -> only use context-entities whose type is set to "ResourceListBuddy"
    • ${BuddyUri}==$(uri) -> only use context-entities that have a variable named BuddyUri which is set to the same value as the one stored in the variable "uri" of this XML entity
    • ${BuddyUri}==$(uris[$(index)]) -> similar to the previous example, but the right-side operand is an array. The variable $(index) is available in destination-requirements whenever the source is an array.
    • ${id}>=$+($(id),3)

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.

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

Example with 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:

Simplified Syntax using references
<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:

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

    Example:
    <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.

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


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.

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

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

  • add_header (optional), when set inserts the specified header into the INVITE message. That attribute can be repeated by adding number at its end, e.g. add_header1=


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 the SIP call id). When empty, no refer will be send.

publish action

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

  • target: the SIP URI to be used in the To: header of the PUBLISH request
  • from (optional): the SIP URI to be used in the From: header of the PUBLISH request (by default the target parameter is used)
  • request_uri (optional): the SIP URI to be used as request URI of the PUBLISH request (by default the target parameter is used)
  • expires (optional, since 10.1.90.1): Value for the SIP Expires: header. If no value is specified the server sets the expiry time. A value of 0 (zero) removes the publication from the server.

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

  • event (optional): Used in the Event: header of the PUBLISH request. The default is "presence".
  • content_type (optional): used in the Content-Type: header of the PUBLISH request. The default is "application/pidf+xml"

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

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

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

    Example:
    <url target="http://myexample.com/test.xml" when="on notify"/>

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:

  • target which holds the digits/tones to be sent.

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:

  • module which names the module to be inquired
  • function specifies the function to use
  • 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

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.

  • The value of the state variable can be any arbitrary string
  • When used for key descriptions the state will be shown in the PUI whenever showing the text representation of the state of the key
  • It defines the behavior of the LED associated with the key in conjunction with the led-settings (e.g. led_on)
  • The state can also be used to determine which other NotifyParsingRules (type = "array" or "variable") to use and which actions may apply.


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:


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>

Further Information


Related articles