.. _macro_phone_functions: Phone Functions --------------- .. index:: Macro function;fn.get_phone_status .. _19.1.1|VOSS-489: .. _19.3.4|EKB-6848: 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 Automate Admin Portal 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 Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +------------------------------------+-----------------------------------+ | Example | Output | +====================================+===================================+ | :: | :: | | | | | {{fn.get_phone_status | "Registered" | | 5ca2b90bce894e0014d488fb, | | | Status}} | | | | | +------------------------------------+-----------------------------------+ .. index:: Macro function;fn.get_phone_statuses * *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 Automate Admin Portal 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 return the phone registration status of these. Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +------------------------------------+-----------------------------------+ | Example | Output | +====================================+===================================+ | | | | :: | :: | | | | | {{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" | | | }] | | | | +------------------------------------+-----------------------------------+ .. index:: Macro function;fn.get_hierarchy_phone_statuses * *fn.get_hierarchy_phone_statuses* A function to retrieve phone statuses as JSON objects with the phone name as the key. including those not returned by the Call Manager API Given as input parameters: * ``status`` - a phone status: The ``status`` parameter value is case insensitive, for example ``Unregistered`` will also find ``UnRegistered``. * Registered * Unregistered * PartiallyRegistered * Rejected * Any * Unknown * None - will return only phones not returned by the Unified CM API; the only data will be hierarchy, phone name and status (None). * optionally followed by value of ``cucm`` (host or pkid) .. note:: * If the function is run at a hierarchy *above* customer level, the parameter is mandatory. * The function will yield an error if more than one ``cucm`` host has the same name. Use the ``pkid`` as value in this case. * optionally followed by value of ``device_name`` (phone name prefix: "startswith" match, e.g. SEP, BOT...) * optionally followed by value of ``ip_address`` (IP address: partial "startswith" match, e.g. "10.10." is valid) * optionally followed by value of ``dir_number`` (directory number: "startswith" match, does not have to be the whole number) semicolon separated list of RIS API field names. The fields below are for example used in the VOSS Automate Admin Portal 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. Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +--------------------------------------+-----------------------------------------------------+ | Example | Output (truncated) | +======================================+=====================================================+ | | | | :: | :: | | | | | {{fn.get_hierarchy_phone_statuses | { | | Registered}} | "CTICTIREM": { | | | "hierarchy": "sys.hcs.CS-P.CS-NB.AAAGlobal", | | | "cm_node": "cucm", | | | "ip_address": "172.29.90.80", | | | "status": "Registered with cucm", | | | "Name": "CTICTIREM", | | | "DirNumber": "82025608-Registered", | | | "DeviceClass": "Phone", | | | [...] | | | | +--------------------------------------+-----------------------------------------------------+ .. index:: Macro function;fn.save_hierarchy_phone_statuses * *fn.save_hierarchy_phone_statuses* A function to retrieve phone statuses as a Comma Separated Value (CSV) file that is stored in the database as an instance of ``data/File`` and accessible from the **File Management** menu on the GUI. The CSV file can for example be exported (as JSON with ``.zip`` extension, containing JSON and CSV files) and managed in a spreadsheet. The ``status`` parameter value is case insensitive, for example ``Unregistered`` will also find ``UnRegistered``. The CSV filename format *with* a parameter value for ```` is: * *____.csv* *otherwise*, the CSV filename format is: * *___.csv* The ** format is: ``%Y%m%d_%H%M%S`` Input parameters as with *fn.get_hierarchy_phone_statuses*, and: * optionally followed by a value of ``fname_prefix`` (CSV filename prefix) Examples: .. tabularcolumns:: |p{8cm}|p{7cm}| +---------------------------------------+--------------------------------------------------------------+ | Example | Output (also refer to data/File instance) | +=======================================+==============================================================+ | | | | :: | :: | | | | | {{fn.save_hierarchy_phone_statuses | { | | Registered}} | "url": "/api/data/File/5bf43f83affa931c2505f6a6/", | | | "description": "AAAGlobal_Registered_20201014)161506_3" | | | } | | | | +---------------------------------------+--------------------------------------------------------------+