Features/Mass Deployment/Setting Files/XML/XmlSubTags/action/assign

From Snom User Wiki

Jump to: navigation, search

Contents

General

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-trees contain at least two sub-tags: source and destination. Both sub-tags have some common attributes:

  • context defines where a variable can be found. It can be set to these 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)
    • language (since 8.7.4):
      • the source (not valid in destinations) refers to a translation
    • call (since 8.7.4):
      • the source (not valid in destinations yet) refers to all calls currently present on the phone
    • 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
  • id defines the name of an array or variable, or when ="state" says the the source or destination is the state of the referred context. This attribute is evaluated differently when found in source or destination tags, please see the detailed description of these tags 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. See these 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 previous example, but right-side operand is an array. The variable $(index) is available
in destination-requirements whenever the source is an array.

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

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.

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. Those function(name)s currently exist:

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

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

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

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" id="name"/>
   <source context="this entity" id="number"/>
   <join value="$(src0) (Tel: $(src1))"/>
   <destination context="this entity" id="label"/>
 </assign>
 <assign when="on notify">
  <source context="this entity" value="right center left" separator=" "/>
  <destination context="this entity" id="label_align[]"/>
 </assign>
 <assign type="update on change" when="after initialization">
   <source context="identity" id="state" require1="${id}==$(identity)"/>
   <destination context="this entity" id="state"/>
 </assign>
 <assign when='on notify' states='ringing'>
   <source context='language' id='linestate_ringing'/>
   <destination context='this entity' id='label[0]'/>
 </assign>
 <assign when='on press'>
   <source context='call' id='id' require='${preping_for_transfer}'/> 
   <destination context='local' id='transfer_id'/>
 </assign>
 <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>
Personal tools
Interoperability