Get-CSSessions: Retrieve, filter, search on ALL user sessions from Skype Online

Office 365, PowerShell, Skype for Business

Introduction

For Skype Online there are various tools to report on user sessions:

  • Call Analytics - This is great for looking at a user’s call history when diagnosing call issues. This is similar to the data we can glean from on-premises SSRS reports.

  • Call Quality Dashboard - Again, great for looking at overall trends or metrics of call quality to pinpoint issues.

  • Session Details - This is accessed from the Skype Admin Centre. Reports are very similar to Call Analytics.

  • Get-CSUserSession - Part of the Skype Online Connector module. This returns the same dataset as the reports above. You can specify a user, start time and end time and it will retrieve the sessions. One big drawback is it will only ever get the first 1000 sessions, so if there are more than 1000 sessions between the start and end time, you don’t get all sessions.

Whilst these tools are great for looking at a particular user or trend, I struggle to use them to answer some of the questions I get asked. For example:

  • Can you tell me who called X number on Y date? Maybe someone has lodged a complaint and you need to investigate who made the call to that person’s number? Maybe someone is making calls they shouldn’t? Using the above tools, if you have 5 users this won’t be too bad to track down. If you have 5000 users you can see how this could take some time.
  • Can you tell me how many calls each user has made/received over a period of time? Again, we can use the above tools against each user, but in large numbers, this could take some time.
  • How many calls did we receive for call queue X yesterday?
  • Can you tell me which user was sending IMs to X on Y date?

Surely there is a better way?

Rather than reinventing the wheel, I looked to see if anyway had what I was after:

  1. Search through all users, (this includes Call Queue ‘users’) and retrieve each of their session details automatically.
  2. Specify a start and end time and gather ALL sessions in that timeframe, not just the first 1000 sessions.
  3. Specify a particular ToURI/FromURI to search for.
  4. Remove sessions I don’t need - Incomplete sessions, RegisterEvent etc.
  5. Export relevant sessions.

Whilst there are some scripts out there, nothing did what I wanted. The closest I came was with Microsoft employee Jason Shave’s excellent CxdCallData. It didn’t tick all the boxes but looking at the code did help me with how to deal with expiring sessions and a recursive search of sessions.

Introducing Get-CSSessions

Firstly I’d like to say outside of a couple oneliner’s I’ve never written in PowerShell before. If my script is doing something terrible or there is a better way to do it, please let me know. I’m sure there might be a more elegant way to code this!

This script is based on the Skype Online Connector module (so will need to be installed to run this) and more specifically our old friend Get-CSUserSession cmdlet. The default behaviour is to connect to Skype Online and retrieve all Skype-enabled users in Skype Online - this can be hybrid or 100% ‘Pure’ cloud users.

With that list, it will go through each user and retrieve all their sessions that were completed within the set time frame. If the PowerShell session to Skype Online reaches 45 minutes, it will disconnect, reconnect and carry on from where it left off (if you provide the PSCredential using -Credential it will do this without prompting again). Likewise, if any timeout errors are noticed it will create a new session and carry on from where it left off.

Once all sessions are retrieved, it will output to a specified CSV file or to GridView. Each session will contain the User from where the session came from, StartTime (UTC), EndTime (UTC), To/From URI, To/From TelNumber (which is masked), To/From ClientVersion, ReferredBy and DialogID (unique to that session). Side Note: Teams PSTN calls also appear in the sessions.

The bare minimum to run the script involves specifying -DaysToSearch (how many days to search back from the current time), -SessionType (All, Audio, Conference, IM or Video), -OutputType (CSV or GridView). If you are outputting to a CSV file, you also need to specify -CSVSavePath (where to save the .CSV file to).

For example, if I want to search for audio sessions for the last 10 days from now and output to a CSV I would run:

.\Get-CSSessions.ps1 -DaysToSearch 10 -SessionType Audio -OutputType CSV -CSVSavePath c:\temp\sessions.csv

Enter your credentials for Skype Online when prompted. Whilst the script is running you can see the percentage complete (based on user numbers, not sessions), the current user that is being processed, the Skype Online session timer, the script runtime and total processed sessions (so far).

As Get-CSUserSession cmdlet returns all sessions, there is no way to speed up the retrieval by asking just for the sessions we want. The script has to go through each session individually and filter out each session based on the provided criteria. In my experience Get-CSUserSession, it can return about 30-60 sessions per second. So, if you have a user base in the 1000s, try not to go too far back otherwise it could take a while. To test large scale, I went through 3 million sessions in around 12 hours.

Command line options

You can modify the default behaviour in the following ways:

  • Add -Credential <PSCredential> To use a PSCredential variable. This is useful if the script is going to run for a while and need to reconnect to Skype Online more than once. It will stop you having to re-enter your credentials again. As with any PSCredential generated with Get-Credential - it doesn’t’ support MFA-enabled accounts. If your account is using MFA, don’t use this or set up another account without MFA.
  • Add -AllInformation to export all session information. Default behaviour doesn’t include all details such as QoE reports - for that, I would use the Call Analytics. Retrieving all the information can make a CSV output get quite large (about 15+ times the size of the default output) and the script will consume more memory in doing so.
  • Add -User <SipAddress> (with or without sip:) to search for a particular user’s sessions only.
  • Add -URI <URI> to search for a particular to/from URI. Can be a complete or partial URI. For example, if I want to see any sessions for +44121 I would use -URI +44121. Useful for tracking down who was involved in a particular session against multiple users, without having to check each user in turn.
  • Add a defined End Date using -EndDate. This will change the End Date from being the time you start the script. Useful if I want to search over a two day period 6 months ago and not bring back 6 months of data back. This uses the PowerShell DateTime format, so it is in American date format and can accept a date only or date and time e.g. -EndDate “04/22/2018” and -EndDate “04/22/2018 18:00” are both fine.
  • Add -IncludeIncomplete to include incomplete sessions (sessions with no EndTime so session looks to have never started e.g. an unanswered call). In my scenarios, I’m generally not worried about sessions that didn’t take place. When Attendant ring type is used in large Call Queues, users sessions can be full of incomplete audio sessions as the calls are answered by other agents, so I’d rather not see them. If there is a requirement to see all sessions, use this.
  • (Added in v1.1) Add -ImportUserCSV <Path to CSV> to search for specified users within CSV file. Users need to be under the User header and specified using their SIPAddress (with or without sip:).
  • (Added in v1.2) Add **-ClientVersion **to search for specified ClientVersions. Can be complete or incomplete ClientVersion. For example “CPE” would return all Lync Phone Edition sessions.

Grab it now!

You can find the latest version at GitHub. Any updates I make to the script will be documented here. Any feedback, (good or bad) or suggestions are welcome.

Let me know how you find the tool and how you use the data.

Version History

  • v1.0 - Initial Release
  • v1.1 - Added ability to specify group of users from CSV file
  • v1.2 - Added ClientVersion filter