Phone Functions#

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:

    Example

    Output

    		 
    {{fn.get_phone_status
      5ca2b90bce894e0014d488fb,
      Status}}

    "Registered"

  • 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:

    Example

    Output

    		 
    {{fn.get_phone_statuses
      5ca2b90bce894e0014d488fb;
      3da7c60bd4632f1113a255dc,
      Status;
      ip_address}}

    [{
  "Status": "Registered",
  "ip_address": "172.29.90.80"
 },
 {
  "Status": "Registered",
  "ip_address": "172.29.90.11"
 }]

  • 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:

    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",
   [...]

  • 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 <fname_prefix> is:

    • <fname_prefix>_<hierarchy_name>_<status>_<timestamp>_<number of entries>.csv

    otherwise, the CSV filename format is:

    • <hierarchy_name>_<status>_<timestamp>_<number of entries>.csv

    The <timestamp> 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:

    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"
 }