Contents





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.

    One xml entity context is tied to each setting that may be described using XmlSubTags, find a list here. You may define variables and arrays as you want and place whatever you want inside. 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
    --  When used for key descriptions the state will be shown in PUI whenever showing the text representation of the state of the key 
        (i.e. in 8xx/760 virtual key view and 760/820/821 side screen). 
    --  Also defines the LED associated with the key in conjunction with the led-settings (e.g. led_on);
    --  The state is also used to determine which NotifyParsingRules (type = "array" or "variable") to parse and which actions may apply. 
    - type: a arbitrary string set during configuration, it never changes unless the setting gets a new configuration provisioned.
    - id: and unique identifier for the entity (e.g. 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 PUI.

    The context 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)
      • the Source is a setting
        The setting context allows to read settings. The individuals settings are saved as variables and arrays in the setting-context, you can access them via the id-attribute.
    • language (since 8.7.4):
      • the Source (not valid in destinations) refers to a translation

        The language contexts provide access to translations. You may specify the word or phrase you want using internal variable names. Simply name it in the id-attribute of your assignment-source.
        You may see all possible names and their translations by looking into the xml's presented here.
        Their format is explained here.
        The translation is done using the same language map that the phone-UI is set to use.

    • 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. There is (yet) a small number of variables you can read / access:

        - 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 of the identities on the phone. There is (yet) a small number of variables you can read (changing variables of identities is not supported):

        - state: the registration state of the identity (registered, registering, failed, 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
        
  • 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>