Report Exchange 2010 Retention Policy Expiration Information for items on a mailbox (EWS)

Outlook 2010 or Outlook 2013 displays retention information for items on Exchange 2010 but the issue is users usually do not check items which will get expired and causes complaints from time to time. One of the requests was to send a report to user showing items that will expire on certain time period. This is why a few weeks ago I started working on this EWS Script to report each item in a mailbox for retention expiration information.

This script will also help admins to report retention policy tags that applied on items while they are testing Retention Policies.

Description

This script reports Retention Information for all items on a requested mailbox. You can have CSV, HTML or both reports as output, which ever suits you best.

Version Information and Update Information

  • Version 1.0 Released : 18 January 2013

Coming soon…

The following features will be added soon. If you want to request any feature please leave a comment.

  • Email User with the report.
  • Set and Run as Scheduled Job.
  • Add Retention Policy Information to HTML Report

Download

You can download the script from HERE.

Prerequisites

There are some important requirements that needs to be completed before running this script:

  • If you have NOT installed EWS Managed API 2.0 download and install it from to the computer that you will be running this script: http://www.microsoft.com/en-us/download/details.aspx?id=35371
  • You need to import Exchange 2010 snap-in to your PowerShell session or you need to use Exchange Management Shell (Easiest way is to install Management tools and run the script on EMS). If you installed the Exchange 2010 Management tools on your computer you can use: add-pssnapin Microsoft.Exchange.Management.PowerShell.E2010 to add the snap-in to your sessions.
  • This script uses Impersonation. The account you are using for reporting must have impersonation rights on Exchange 2010. For more information on Impersonation:http://msdn.microsoft.com/en-us/library/exchange/dd633680(v=exchg.80).aspx
  • I usually like to use scope for impersonation for security reasons. If you do not care; you can use the following command to give the account impersonation rights that you will be using to run this script:
    • New-ManagementRoleAssignment –Name:impersonationAssignmentName –Role:ApplicationImpersonation –User: YourAccount
  • Exchange 2010 Throttling Policy might cause reporting have missing items. (Even though I am using default values of 1000 for EWSFindCountLimit on the script) If you are going to use this script against large mailboxes make sure Throttling policy is set correctly as it might take longer than expected to get all the information. For more information on Exchange 2010 EWS Throttling please read: http://msdn.microsoft.com/en-us/library/exchange/hh881884(v=exchg.140).aspx. For some cases I have created a policy for this script with the following settings to speed it up:
    • Set-ThrottlingPolicy RetentionPolicyReport -EWSMaxConcurrency $null -EWSPercentTimeInAD $null -EWSPercentTimeInCAS $null -EWSPercentTimeInMailboxRPC $null -EWSMaxSubscriptions $null -EWSFastSearchTimeoutInSeconds $null -EWSFindCountLimit $null -CPUStartPercent $null

*This is not recommended please set the throttling policy according to your needs.

  • This script is using code that Glen Scales wrote for making connections to EWS. Please review lines: 129 to 193 and set the desired connection method. Currently script is going to use current credentials for the logged on user and will use AutoDiscover to determine the EWS address for the mailbox you requested to report. Please read http://gsexdev.blogspot.com/2012/01/ews-managed-api-and-powershell-how-to.html , Glen clearly explains what you need to connect.
  • Script is set to use Exchange 2010_SP2 for exchange version. (Line: 131)

Script Usage and Examples

If all these requirements are set, you are ready to get report on any item on any mailbox (no scoped impersonation required) for Retention information. You can download and save the script to a directory on the computer that you will be running this script. Make sure you have write permission on this directory as the script will be creating the report in the same directory.

Here are some other examples for the script usage:

  • .\Get-RetentionExpiration -Identity Serkan -HTMLReport
    • This will create a HTML Report for Serkan user and will include all mailbox items. HTML Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -CSVReport
    • This will create a CSV Report for Serkan user and will include all mailbox items. CSV Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -CSVReport -HideNeverExpires
    • This will create a CSV Report for Serkan user and will include all mailbox items. If item does not have any expiration date it will be excluded. CSV Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -OnlyTheseFolders “\Inbox*”,”Drafts” -CSVReport
    • This will create a CSV Report for Serkan user and will include Drafts, Inbox and Inbox Subfolders. CSV Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -ExcludeFolders “\Conversation History*”,”Temp” -CSVReport
    • This will create a CSV Report for Serkan user and will EXCLUDE Temp, Conversation History and Conversation History Subfolders. CSV Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -ExpiresInDays 60 -CSVReport
    • This will create a CSV Report for Serkan user for items that will expire in next 60 days. CSV Report will be saved in the same folder as the script.
  • .\Get-RetentionExpiration -Identity Serkan -ExpiresInDays 30 -CSVReport -HTMLReport
    • This will create a CSV Report for Serkan user for items that will expire in next 30 days. Both HTML Report and CSV Report will be saved in the same folder as the script.

Here is the screenshot showing the script process:

Get-RetentionExpiration

Here is an example HTML Report, I filtered a certain folder for this example using the –OnlyTheseFolders Parameter.

Folder Name Subject Recieved Date Expiration Date Size Retention Tag
\USER FOLDERS\5 Year Retention Cigdem V, Ticket #1234 01/15/2013 09:12:02 01/14/2018 13:12:02 11161 5 Year
\USER FOLDERS\5 Year Retention CV 12/14/2012 09:30:58 Never Expires 2700 99 Year
\USER FOLDERS\5 Year Retention Had to rename this subject :) 12/12/2012 11:22:17 12/11/2017 15:22:17 2548 5 Year
\USER FOLDERS\5 Year Retention Another Report 11/18/2011 20:37:12 11/17/2016 00:37:12 4775 5 Year
\USER FOLDERS\99 Year Retention Exchange 2010 Retention Script 01/15/2013 11:07:32 Never Expires 4130 99 Year

Note: If the item retention policy tag does not match the folder retention policy tag it will be highlighted on HTML report.

Please let me know if you have any questions or help for this script. I hope it helps.

In addition I would like to thank Glen Scales for his contributions on EWS on his blog.

About Serkan Varoglu

Serkan Varoglu is a Turkish IT Pro living in Ireland. Serkan has over 10 years experience and hold certifications including MCITP (EMA 2010 and Enterprise Admin), MCSE, MCSA, MCTS, ITIL and was awarded the Microsoft MVP Award (Exchange Server).