How to use the Office 365 Call Quality Dashboard PowerShell module

The Call Quality Dashboard (CQD) PowerShell module allows administrators to access network and call quality information gathered by Microsoft Teams and Skype for Business. This post introduces this resource, including how to install the module and perform basic queries.

The Call Quality Dashboard (CQD) available in Office 365 for Microsoft Teams and Skype for Business is not a new tool. It was born from its on-premises server counterpart and translated for cloud usage. CQD is a collection of performance and diagnostic data gathered by the Teams or Skype client during an audio call, video call, or screen-sharing session.

At the end of each session, the client packages and uploads this quality-of-experience data to a central reporting database. CQD provides a portal for analyzing this data and providing additional insights into the quality of these services. For example, you can build custom reports to see where on the corporate network audio calls are performing poorly.

CQD allows for building reports and tables of data and provides a mechanism for extracting the data in the portal. However, if you have multiple reports used to extract data on a regular basis, this can be a tedious process to export the data from the portal manually. To assist with this process, Microsoft has built an API that allows extraction of this data, and on top of that, they have provided a PowerShell module that uses simple commands to extract the data.

If you are unfamiliar with CQD, I would suggest checking out the following resources first:

Microsoft docs: CQD basics

Microsoft on YouTube: Skype Operations Framework (SOF) CQD training series

First, let's discuss how to install this PowerShell module. Microsoft provides this module via the PowerShell Gallery repository. Hosting the module here allows for installing it directly from a PowerShell prompt using the Install-Module command. If you have never installed a module from the PowerShell Gallery, you may receive prompts about installing additional software as well as trusting the remote repository.

Installing the CQD PowerShell module

Installing the CQD PowerShell module

The CQDPowerShell module has three commands:

  1. Get-CQDData
  2. Get-CQDDimensions
  3. Get-CQDMeasures

While Get-CQDData is the workhorse in this module, we will not get far without the dimensions and measures. Dimensions and measures determine what kind of data we want to extract and how to group the data. Running the Get commands will display the property names we need later. These are some examples of the dimensions and measures returned from these commands:

Examples of available dimensions and measures

Examples of available dimensions and measures

Before we get into extracting data using these properties, let's look at a built-in report in CQD to understand why they are important. This is a typical report with the number of good, unclassified, and poor audio streams as well as the percent of poor audio streams. Given this is a small demo tenant, there's not much in the way the chart looks, but that's not what we're focusing on.

CQD example report

CQD example report

If we edit this report, we will see that these chart properties are all measurements, and they are grouped by month and year or a dimension:

Report details showing dimensions and measurements

Report details showing dimensions and measurements

Looking at the left side of the edit window, we see the full names of the dimensions and measures used for building the report. Using the Get-CQDDimensions and Get-CQDMeasures commands and some filtering, we can find the equivalent names of these properties for our PowerShell command:

Searching for matching dimensions and measures

Searching for matching dimensions and measures

These are translations from the CQD report to the PowerShell equivalents:

  • Month Year > AllStreams.Month Year
  • Audio Good Call Stream Count > Measures.Audio Good Call Stream Count
  • Audio Poor Call Stream Count > Measures.Audio Poor Call Stream Count
  • Audio Unclassified Call Stream Count > Measures.Audio Unclassified Call Stream Count
  • Audio Poor Call Percentage > Measures.Audio Poor Call Percentage

We now have all the pieces to get the CQD through our PowerShell command. The Get-CQDData command has several parameters, but the ones we are interested in for now are Dimensions, Measures, and OutPutType. We will build the command using the PowerShell names of the same dimensions and measures used in our report. Since there are spaces in them, we need to enclose each one in quotes and separate multiple ones with commas, and we will output the data into a DataTable:

Get CQDData command with dimensions and measures

Get CQDData command with dimensions and measures

By running this command, we now have the same data from our report listed in a PowerShell window, and we can save it to a variable or export it to a CSV file using other parameters of Get-CQDData. From here, I would recommend continuing to build reports in the CQD portal, and at the same time, find the PowerShell names of the dimensions and measures to build the equivalent command. This will allow you to automate the extraction of the data to ingest it into other tools for analysis. This can be a big time-saver if you are constantly going into the CQD portal to download this data manually.

Join the 4sysops PowerShell group!

Your question was not answered? Ask in the forum!

1+
Share
14 Comments
  1. Michael Markl 1 year ago

    Hi Jeff,

    great article!

    Was really working for me. But...

    When I'm trying to add the dimension 'AllStreams.is Teams' I got "Error Querying CQD with Error 6" I assume this is due to the fact that the module is checking on cqd.lync.com and not on the CQDv3 link?
    If so, can I change this?
    Best regards

    Michael

    0

    • Author

      Hi Michael, I tried the following command and I got results back:

      I tried a lowercase 'i' for 'is Teams' and got the Error 6 you are referencing. It seems the API is case-sensitive! Very interesting.

      The question on the old versus CQDv3 is a good question. Not sure how the module will work with the upcoming changes in the platform.

      0

  2. Michael Markl 1 year ago

    Hi Jeff,

    I’m a bit embarrassed about the case-sensitive thing, but at the end you saved my day and that’s the important thing to look at 😊

    Tried also on my side and it is working too.
    This module is definitely what I was looking for. Thank you so much!!!

    Best regards

    Michael

    0

  3. Michal 1 year ago

    Hello Jeff,

    Very nice module indeed. I have walked through the code and already made some improvements. I have added a "universal filter" to the code, so you can customize the query more effectively.

    For example you will append your query with parameter -universalfilter @('First Subnet=192.168.1.0','Month Year=2019-06')
    It believe it is self explanatory, and you can append unlimited number of filters here.

    I am willing to share if you agree, maybe we can work together on enhancements 🙂

    Also I would like to ask if it is possible to add appid/secret authentication instead of windows form.

    Thanks

    Michal

     

    1+

  4. Victoria E 12 months ago

    Hi, So I had no problems with installing the CQDpowershell. However, when I try to run the import-module CQDpowershell, and after entering my credentials, I am immediately hit with:" The resource you are looking for has been removed, had its name changed, or is temporarily unavailable."

    I can't find anything on the internet that lets me resolve it. Any suggestions?

    0

    • Author

      Hi Victoria, what permissions do you have in Office 365? That's the first thing that comes to mind, you'll need Global Admin or Skype Admin at a minimum.

      0

  5. Maxime M 11 months ago

    Hi,

    I have installed the module, then just trying the Get-CQDDimensions and received following error:

    Invoke-WebRequest : Le nom distant n'a pas pu être résolu: 'cubestructure'
    At C:\Program Files (x86)\WindowsPowerShell\Modules\CQDPowerShell\1.11\CQDPowerShell.psm1:201 char:18
    + ... beRequest = Invoke-WebRequest -Uri ('{0}CubeStructure' -f $DataServic ...
    +                 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        + CategoryInfo          : InvalidOperation: (System.Net.HttpWebRequest:HttpWebRequest) [Invoke-WebRequest], Web
       eption
        + FullyQualifiedErrorId : WebCmdletWebResponseException,Microsoft.PowerShell.Commands.InvokeWebRequestCommand

    Have you ever encoutered that ?

    0

  6. Tame 11 months ago

    You mentioned these commands work for MSFT Teams. Is that correct? Is there any ref that I can refer to? 

    0

  7. Jason 6 months ago

    Why is there no measure for total call count

     

    0

  8. vishnu 5 months ago

    For automation, the PS script prompts for O365 authentication each time. How can this be handled/ bypassed ?

    5+
    avatar
    • You could save your (or some management account) password hash to the script, or a file or a registry. If you run the script on the same machine under the same account each time, it should work. Tho storing passwords in scripts is not considered as a security best practice (even the password hash is encrypted by the machine and account RSA key).

      0

  9. Irfan Maroof 4 months ago

    I am running the script with following command and I am login on powershell with my account and it is not asking for any other credentials.

    Get-CQDData -Dimensions 'AllStreams.Month Year' -Measures 'Measures.Audio Good Call Stream Count','Measures.Audio Poor Call Stream Count','Measures.Audio Unclassified Call Stream Count','Measures.Audio Poor Call Percentage' -OutPutType DataTable

     

    Get-JWTData: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:178

    Line |

     178 |      $JWTDecoded = Get-JWTData $Script:Token

         |                                ~~~~~~~~~~~~~

         | Cannot bind argument to parameter 'Token' because it is an empty string.

     

    Invoke-WebRequest: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:252

    Line |

     252 |  … beRequest = Invoke-WebRequest -Uri ('{0}CubeStructure' -f $DataServic …

         |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         | nodename nor servname provided, or not known

     

    ConvertFrom-Json: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:253

    Line |

     253 |    $List = ConvertFrom-Json $CubeRequest

         |                             ~~~~~~~~~~~~

         | Cannot bind argument to parameter 'InputObject' because it is null.

     

    PS /Users/irfanmaroof/code/cronacrisis> Get-CQDData -Dimensions 'AllStreams.Month Year' -Measures 'Measures.Audio Good Call Stream Count','Measures.Audio Poor Call Stream Count','Measures.Audio Unclassified Call Stream Count','Measures.Audio Poor Call Percentage' -OutPutType DataTable

    Get-JWTData: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:178

    Line |

     178 |      $JWTDecoded = Get-JWTData $Script:Token

         |                                ~~~~~~~~~~~~~

         | Cannot bind argument to parameter 'Token' because it is an empty string.

     

    Invoke-WebRequest: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:252

    Line |

     252 |  … beRequest = Invoke-WebRequest -Uri ('{0}CubeStructure' -f $DataServic …

         |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         | nodename nor servname provided, or not known

     

    ConvertFrom-Json: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:253

    Line |

     253 |    $List = ConvertFrom-Json $CubeRequest

         |                             ~~~~~~~~~~~~

         | Cannot bind argument to parameter 'InputObject' because it is null.

     

    Get-JWTData: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:178

    Line |

     178 |      $JWTDecoded = Get-JWTData $Script:Token

         |                                ~~~~~~~~~~~~~

         | Cannot bind argument to parameter 'Token' because it is an empty string.

     

    Invoke-WebRequest: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:252

    Line |

     252 |  … beRequest = Invoke-WebRequest -Uri ('{0}CubeStructure' -f $DataServic …

         |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         | nodename nor servname provided, or not known

     

    ConvertFrom-Json: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:253

    Line |

     253 |    $List = ConvertFrom-Json $CubeRequest

         |                             ~~~~~~~~~~~~

         | Cannot bind argument to parameter 'InputObject' because it is null.

     

    New-Object: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:790

    Line |

     790 |  … Attribute = New-Object System.Management.Automation.ValidateSetAttrib …

         |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         | A constructor was not found. Cannot find an appropriate constructor for type System.Management.Automation.ValidateSetAttribute.

     

    New-Object: /Users/irfanmaroof/.local/share/powershell/Modules/CQDPowerShell/2.0.0/CQDPowerShell.psm1:791

    Line |

     791 |  … Attribute = New-Object System.Management.Automation.ValidateSetAttrib …

         |                ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

         | A constructor was not found. Cannot find an appropriate constructor for type System.Management.Automation.ValidateSetAttribute.

     

    Working....

    Error Binding

    0

  10. Vishnu 4 months ago

    $UserName = "abc"

    $SecurePassword = Read-Host -Prompt "Enter password" -AsSecureString 

     $Creds = New-Object System.Management.Automation.PSCredential -ArgumentList $UserName, $SecurePassword

    $Session = New-PSSession  -ConnectionUri https://cqd.teams.microsoft.com/ -Credential $Creds -Authentication Basic -AllowRedirection

    Import-PSSession $Session   

    Get-CQDData -CQDVer V3 -Dimensions 'AllStreams.Month Year' -Measures 'Measures.Avg Call Duration','Measures.Audio Call Count' -outPutType DataTable -MediaType 'Audio'  | format-table

    Session variable is not working and gives popup for O365 auth. what needs to be tweaked to get this working?

    0

  11. Manish R. Patel 4 months ago

    Yes need script to automate and schedule in task schedular.

    Tried multiple time but it is asking for credentials for connecting to Microsoft call quality dashboard

    0

Leave a reply

Your email address will not be published. Required fields are marked *

*

© 4sysops 2006 - 2020

CONTACT US

Please ask IT administration questions in the forums. Any other messages are welcome.

Sending

Log in with your credentials

or    

Forgot your details?

Create Account