.. _macro_phone_functions:

Phone Functions
---------------

.. index:: Macro function;fn.get_phone_status
.. index:: Macro function;fn.get_phone_statuses

.. _19.1.1|VOSS-489:


Function names:

* *fn.get_phone_status*

  Given as input parameters:
   
  * a phone PKID
  * followed by a comma and then exactly one 
    RIS API field name. 
    
    The fields below are for example used
    in the VOSS-4-UC GUI list view of Phones:
  
    * ``status``
    * ``ip_address``
    * ``cm_node``
  
    To see a full list of available fields, refer to the Cisco RIS API documentation.

  Returns:
  
  A string with the results according to the selected field name

* *fn.get_phone_statuses*

  Given as input parameters:
   
  * a semicolon separated list of phone PKIDs
  * optionally followed by a comma and then a 
    semicolon separated list of RIS API field names.
    
    The fields below are for example used
    in the VOSS-4-UC GUI list view of Phones:
  
    * ``status``
    * ``ip_address``
    * ``cm_node``
  
    To see a full list of available fields, run the macro function without
    RIS API field names or refer to the Cisco RIS API documentation.
  
  Returns:
  
  A list of phone status results with details:
  
  * containing either all fields if no optional field name
    list was provided, or
  * if an optional field name list was provided,
    results according to the selected field names.


.. note::

   This function will query the Unified CM for the requested PKIDs
   and save the phone registration status of these to the VOSS-4-UC database.


Examples:

.. tabularcolumns:: |p{8cm}|p{7cm}|

+------------------------------------+-----------------------------------+
| Example                            | Output                            |
+====================================+===================================+
| ::                                 | ::                                |
|                                    |                                   |
|    {{fn.get_phone_status           |    "Registered"                   |
|          5ca2b90bce894e0014d488fb, |                                   |
|          status}}                  |                                   |
|                                    |                                   |
+------------------------------------+-----------------------------------+
|                                    |                                   |
| ::                                 | ::                                |
|                                    |                                   |
|    {{fn.get_phone_statuses         |    [{                             |
|          5ca2b90bce894e0014d488fb; |      "status": "Registered",      |
|          3da7c60bd4632f1113a255dc, |      "ip_address": "172.29.90.80" |
|          status;                   |     },                            |
|          ip_address}}              |     {                             |
|                                    |      "status": "Registered",      |
|                                    |      "ip_address": "172.29.90.11" |
|                                    |     }]                            |
|                                    |                                   |
+------------------------------------+-----------------------------------+