.. _macro-dot-notation:

Dot notation
------------

.. _25.3|EKB-26195:


Overview 
...........

Dot notation is used to reference macro functions, model attributes, defined 
variables, step references, and non-attribute values in the model schema. 

Dot notation is a structured way to access: 

* Macro functions 
* Model attributes 
* Defined variables 
* Workflow steps 
* Non-attribute metadata 

It is a pathing syntax that lets you drill into specific values or functions within 
the platform's data models and templates. 


Syntax patterns and usage 
............................

* ``fn.macrofunction_name``

  Calls a macro function. See the **Macro Functions** section in the Advanced Configuration Guide. 

* ``self.attribute``

  Refers to the current model's attribute.

  .. note:: 

     ``attribute`` must be a valid attribute name of the calling model (typically within a configuration template).

* ``previous.attribute``

  Retrieves the previously saved value of an attribute. Useful when comparing against the current value 
  during model updates.

* ``input.attribute``

  Identifies values provided via GUI input, bulk load, provisioning workflow foreach variable or context. 

* ``pwf.variablename``

  References a variable defined in a provisioning workflow step.

* ``cft.attribute``

  Access values from the current ``context_var`` of a ``foreach`` loop within a configuration template.

* ``modelname.attribute``

  Defaults to referencing the data model type.

* ``modeltype.modelname.attribute``

  Used for non-data model types. 

* ``modeltype.modelname.attribute.NUMBER``

  Refers to a specific indexed attribute (zero-based), referring to attribute NUMBER-1 where there is 
  more than one attribute. 
  
  Example: ``modeltype.modelname.attribute.0`` accesses the first item. See section *Macro examples*. You can also 
  use a wildcard: 
  
  ::

    {# device.cucm.Phone.lines.line.\*.dirn #}

* ``macro.name``

  References a defined macro by name.

* ``workflow.stepSTEPNUMBER.pkid``

  Overrides the context hierarchy by specifying the ``pkid`` of a workflow step. 
  
  Example: ``workflow.step2.pkid``


.. _non-attribute-notation:

Non-attribute notation 
..........................

These metadata (special) fields are used for hierarchy and identification and can be accessed using dot-notation: 

* ``__pkid``
* ``__bkey``
* ``__hierarchy``
* ``__hierarchy_friendly_path``
* ``__hierarchy_friendly_parent_path``


.. rubric:: Examples: 

::

  {# data.Countries.__pkid #}
  {# data.CallManager.__bkey #}
  {{ data.CallManager.__bkey | host:172.29.248.150 }}
  {{ data.CallManager.__hierarchy | host:172.29.248.150 }}
  {{ data.CallManager.__hierarchy_friendly_path | host:172.29.248.150 }}
  {{ data.CallManager.__hierarchy_friendly_parent_path | host:172.29.248.150 }}


.. rubric:: Including the unique ID for each instance of special fields 
  
You can use a wildcard (*) appended to ``__pkid`` with any of the special (metadata) fields in a macro 
query to return all fields plus the unique identifier for each instance. 

Examples:  

* ``{# data.Countries.*,__pkid #}``
* ``{# data.Countries.*,__pkid,__hierarchy_friendly_path,__hierarchy,__bkey #}``

A unique ID is required for each instance when using a 
wildcard since it is not possible to rely on all fields to be unique. This is useful for overbuild workflows or 
any scenario requiring unique identification. 

For example, macro ``{# data.Countries.*,__pkid #}`` returns all countries in the 
database, plus the pkid. This syntax ensures that the macro output includes all fields and the unique 
identifier for each instance. 

:: 

   {
        "country_name": "Australia",
        "iso_country_code": "AUS",
        "iso_country_code_short": "AU",
        "international_dial_code": "61",
        "international_access_prefix": "011",
        "premium_access_prefix": "8",
        "emergency_access_prefix": "000",
        "service_access_prefix": "13",
        "national_trunk_prefix": "0",
        "pstn_access_prefix": "9",
        "default_user_locale": "English United States",
        "network_locale": "United States",
        "__pkid": "63f7885cc33191b9204fa73e"
    },


.. image:: /src/images/wildcard-with-pkid-macro-1.png 


.. rubric:: Combining hierarchy fields 

The ``hierarchy`` fields can be combined with model attribute names in a 
comma separated list, for example:


::

   {# data.Countries.country_name,__hierarchy,__hierarchy_friendly_path #}


Output snippet:

::

    [
        {
            "country_name": "Australia", 
            "__hierarchy": "58d303503f44d58341d61775",
            "__hierarchy_friendly_path": "hcs"
        },
        {
            "country_name": "Bahrain", 
            "__hierarchy": "58d303503f44d58341d61775",
            "__hierarchy_friendly_path": "hcs"
        },

     ...


.. note:: 

   Meta attribute properties can also be used in a macro filter. See 
   *Macro Syntax to Filter by Meta Properties*.


Sequence and looping 
......................


* To indicate sequence instance with ``SEQ`` - the value is a loop sequence number 
  starting from 1 or a wizard step number: 
  
  * It is obtained from a **Foreach List Macro** in a  provisioning workflow or 
    a **Foreach Elements** loop in a configuration template.

    This value can be used to refer to an *attribute* of a model. An array item in a
    configuration template has a **Foreach Elements** loop with a variable ``phoneX``:

    ::

       {# self.Phone.{{fn.subtract input.phoneX.SEQ,1}}.lines.line #}

    that refers to an attribute (line in a list of phones), starting with the first one:

    ``self.Phone.0.lines.line``

  * This value can be used to refer to a *Wizard step* (stepSTEPNUMBER) in its
    configuration template. A **Foreach Elements** loop with a variable ``step``
    that holds a list of STEPNUMBER obtained from the wizard:

    ::

       {# input.define_wizard_steps #}

    so that stepSTEPNUMBER can be incremented with: 

    ``step{{cft.step.SEQ}}``

.. |VOSS Automate| replace:: VOSS Automate
.. |Unified CM| replace:: Unified CM