.. _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-4-UC 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-4-UC 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-4-UC 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" | | | } | | | | +---------------------------------------+--------------------------------------------------------------+