New-ComplianceSearch: how to use the newer version of Search-Mailbox

[Update]: This blog post was updated on April 3, 2020.

As announced in this Microsoft article, the date for retirement of legacy eDiscovery tools is moved from April 1, 2020 to July 1, 2020. That is when Search-Mailbox cmdlet will no longer be available. This means that all scripts using Search-Mailbox need to be rewritten and one of the most basic administrative tools needs to be relearned from scratch. In this article, I will demonstrate how to use the New-ComplianceSearch cmdlet in place of its long-lived predecessor, Search-Mailbox.

New-ComplianceSearch in place of Search-Mailbox

Search-Mailbox end of life

For some time now, the Search-Mailbox cmdlet has been returning a warning that it will soon go out of use. The exact moment of its end of life is set to July 1, 2020 (moved from April 1, 2020). Note that if you are still on Exchange 2010, you also have the server’s end of life to worry about. For those of you who manage Exchange Online – after the April 1 deadline has passed, Search-Mailbox still works, but it returns a warning that the cmdlet is being retired, so learning how to use ComplianceSearch cmdlets is still a must. In modern Exchange on-premises environments, it is recommended to use the new *-ComplianceSearch cmdlets. Let’s see what differences are there between the old and the new method of searching through mailboxes.

Comparison between ComplianceSearch and Search-Mailbox

The Search-Mailbox cmdlet could be used to:

  • restore deleted items (invisible from the users’ perspective),
  • copy certain elements to a discovery mailbox,
  • delete or purge mailbox content,
  • estimate results for a chosen query.

These capabilities, together with the highly customizable -SearchQuery attribute, made this single cmdlet extremely useful. Don’t get me wrong, using this cmdlet was not all roses:

  • You needed to work around the 10.000 results limit.
  • KQL used in the SearchQuery could be a bit clunky, especially when you included multiple conditions. But, to be honest, the -ContentMatchQuery attribute in the new search experience uses KQL as well.
  • There was no way to restore deleted elements to the same mailbox – the target mailbox needed to be different from the searched mailbox.

Now, with the *-ComplianceSearch family of cmdlets, you can get similar results, but the way you do it is a bit like switching from the Message Tracking logs to Office 365 Message Trace. The basic differences are:

  • Search-Mailbox required the Mailbox Search role to perform searches or the Mailbox Import Export role to delete items. *-ComplianceSearch cmdlets require one of those roles AND a security & compliance related role.
  • With Search-Mailbox, you could use a single cmdlet to search and delete some mailbox content while ComplianceSearch requires a few steps.
  • Search-Mailbox (as the name suggests) handled only mailbox-related content. ComplianceSearch is based on Unified Search, so it can also run through SharePoint sites and Public Folders.
  • When it comes to ComplianceSearch cmdlets, starting a remote PowerShell session to Exchange Online will not suffice. You need to connect to the Security & Compliance module as well.
  • Each New-ComplianceSearch you perform can be viewed in Office 365 Compliance Center.
  • New-ComplianceSearchAction is not intended for a mass cleanup of mailboxes, as it only deletes 10 items per mailbox at a time.

Prepare to use Compliance Search

Two prerequisites required before performing any Compliance Search-related actions is connecting to the right Office 365 services. You can do it in a single PowerShell session using the following code:

$credentials = get-credential;
Connect-ExchangeOnline -Credential $credentials
$SccSession = New-PSSession -ConfigurationName Microsoft.Exchange
-ConnectionUri https://ps.compliance.protection.outlook.com/powershell-liveid/
-Credential $credentials -Authentication "Basic" -AllowRedirection;
Import-PSSession $SccSession

You will get prompted for your Office 365 administrator credentials. After that, the console will attempt to perform remote connections to Exchange Online and Security & Compliance PowerShell. The right modules, together with the accessible cmdlets, will be automatically installed and imported.

Read more about prerequisites and troubleshooting for the modern method of connecting to Exchange Online

Next, you need to make sure you have the right permissions. Run the cmdlet below to find out who has access to the Mailbox Search role:

Get-ManagementRoleAssignment -Role "Mailbox Search" -GetEffectiveUsers -Delegating $false 

The easiest way to assign this role is to add yourself to a group which includes this role, for example:

Add-RoleGroupMember "Discovery Management" -member me@example.com

Mind that the Mailbox Search role allows to create searches, but only the Mailbox Import Export role gives admins the right to delete or export the search results.

The next step is to check eDiscovery Admins:

Get-eDiscoveryCaseAdmin

And add yourself to this group, if necessary:

Add-eDiscoveryCaseAdmin me@example.com

How to run a ComplianceSearch cmdlet?

As soon as you are connected and you have the right permissions assigned, you can start a search. First, you need to configure a search with the New-ComplianceSearch cmdlet. For example, you can search through all mailboxes, looking for a certain keyword in the message subject:

New-ComplianceSearch -name "suspicious emails" -ExchangeLocation all -ContentMatchQuery 'subject:"suspicious"'

Or base your search on a date items were received, for example this short script below will return items two days old and newer:

$date= (get-date).adddays(-2);
$date = $date.ToShortDateString();
$date = [scriptblock]::create($date);
New-ComplianceSearch "mailbox items newer than 2 days"
-ExchangeLocation all -ContentMatchQuery "received>=$date"

The -ContentMatchQuery attribute works the same as the -SearchQuery attribute in Search-Mailbox. See a detailed guide on how to use the SearchQuery.

If you want to search through inactive mailboxes, you need an additional attribute: -AllowNotFoundExchangeLocationsEnabled $true. Additionally, if you point your search to a single inactive mailbox, its UPN must be prepended with a period(.), like below:

New-ComplianceSearch "Search inactive mailbox" -ExchangeLocation .samplemailbox@example.com -AllowNotFoundExchangeLocationsEnabled $true

After you set up conditions for the search, you need to run a separate cmdlet to start it:

Start-ComplianceSearch “suspicious emails”

You can also pipeline the New-ComplianceSearch cmdlet to Start-ComplianceSearch, like that:

New-ComplianceSearch … | Start-ComplianceSearch

To check the progress of your search and get some basic info about the current results, run the following cmdlet:

Get-ComplianceSearch | FL name,items,size,jobprogress,status

What happens if you re-run a compliance search?

You can restart any search that has already been finished. That’s good news – it means you can rerun searches with the most common queries. Or use the Set-ComplianceSearch cmdlet to change search criteria and Start-ComplianceSearch immediately afterwards.

How to delete mailbox contents in Office 365 using PowerShell

After you’ve set up and finished the ComplianceSearch, you need to use New-ComplianceSearchAction with the -Purge attribute to delete items, for example:

New-ComplianceSearchAction -SearchName “suspicious emails” -purge -purgetype SoftDelete/HardDelete

If you don’t specify the -PurgeType attribute, the results will be soft-deleted, meaning that users will be able to recover those deleted items until the retention period passes. The HardDelete value purges items for good, unless there is Litigation Hold or Retention Policy set up to prevent deleting certain items. Mind that the “10 items per mailbox” limit of the New-ComplianceSearchAction requires you to perform precision searches or looping the cmdlet.

Learn more about Retention Policies and Litigation Holds in Office 365

Troubleshooting

There are a few common problems you can run into during this procedure. Below, I list the most common errors and ways to counter them.

Not recognized as the name of a cmdlet

One of the most common errors known to PowerShell users is:

New-ComplianceSearchAction: The term 'New-ComplianceSearchAction' is not recognized as the name of a cmdlet, function, script file, or operable program. Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

The problem is that there might be quite a few reasons for this warning to pop up:

  1. Problem: Failed to connect to Security & Compliance Center
    Solution: Run Get-PSSession to check if your remote sessions are Opened and Available. You can use Get-PSSession | Remove-PSSession and repeat the steps from Prepare to use Compliance Search. Make sure to make to use the right credentials.
  2. Problem: Failed to import module with available cmdlets
    Solution: For some reason, your PowerShell session might have been unable to import the right Office 365 services module. To fix it, run Get-Module | Import-Module
  3. Problem: Lack of permissions
    Solution: If you lack permissions, you need to have them assigned to you. If you don’t have enough permissions to assign yourself a member of the right role group, you need to request access from another administrator.
  4. Problem: Connection Timeout
    Solution: Your remote session might time out after a while. To fix it, repeat the steps from prepare to use Compliance Search.
  5. Problem: Misspelled cmdlet
    Solution: I’ve seen New-ComplainceSearch more times than I’m willing to confess. I was even considering creating the New-ComplainceSearch alias for the right cmdlet. Maybe I’m the only one typing the cmdlets manually, but it doesn’t hurt to check your spelling if you do type a cmdlet.

The search is still running

This error appears if you are too hasty or run searches with extremely broad criteria.

Unable to execute the task. Reason: The search "*" is still running or it didn't return any results. Please wait until the search finishes or edit the query and run the search again. 

To speed up the search, make sure you are searching only the relevant directories.

To check the status of Compliance Searches, run:

Get-ComplianceSearch | FL name,items,size,jobprogress,status

The compliance search object already exists

This error is caused by running New-ComplianceSearch with a name that already exists.

The compliance search object "*" already exists within your organization.

To fix it, either use a new unique name, or run Set-ComplianceSearch instead.

CodeTwo Products

11 thoughts on “New-ComplianceSearch: how to use the newer version of Search-Mailbox


  1. You must be Org Management role or assigned to Search and Purge role group to delete messages
    Also, you must use the SCC PS module to delete, otherwise nothing happens.
    You have to be in E-Discovery Manager role or Search Compliance role group to create the content search.

    More than 10 messages, and it becomes much more difficult.

    • That’s why I still use Search-Mailbox for deleting emails. Hope it doesn’t stop working all of a sudden.

  2. The new cmdlet will search OneDrive and SharePoint sites. Is there a way to delete files found in those places? I get an error stating that Purge does not support the SharePoint or OneDrive workload.

    • Unfortunately, neither those cmdlets, nor the compliance search via UI can be used to delete files from SharePoint or OneDrive.

  3. Hi,

    Can you also do the compliance search in the GUI/admin panel, and then call the name through powershell to delete? Or do you need to do everything through Powershell?

    Kind regards,
    Daan

    • Hi Daan,
      Yes, you can Admin Panel to run a compliance search and then delete its results with PowerShell.

  4. I tried the the command without an error
    However it doesn;t delete emails.

    I understand it only delete 10 of email each time.
    So i repeat the process 5 times

    and thought the spam mail has been deleted, i ran query again and bam 142 items still.

    • Have you used the -PurgeType HardDelete attribute? If not, those items are only soft-deleted.

  5. great blogs but here I ran into a problem

    PS C:\temp> Add-RoleGroupMember “Discovery Management” -member xxxxx@xxxx.onmicrosoft.com

    tiggers

    The operation couldn’t be performed because object ‘Discovery Management’ couldn’t be found on ‘FfoRecipientSession’.
    + CategoryInfo : NotSpecified: (:) [Add-RoleGroupMember], ManagementObjectNotFoundException
    + FullyQualifiedErrorId : [Server=DB5EUR03WS010,RequestId=3e29214f-2606-4a24-a404-428677771cda,TimeStamp=28.05.202
    0 16:05:23] [FailureCategory=Cmdlet-ManagementObjectNotFoundException] EF80F707,Microsoft.Exchange.Management.Rbac
    Tasks.AddRoleGroupMember
    + PSComputerName : eur03b.ps.compliance.protection.outlook.com

    All other commands OK
    Can you see what is wrong her?

    • It looks like you might not have sufficient permissions to runt this cmdlet. See if you can add members to this role group using Exchange Admin Center, or ask a global admin to assign permissions.

Leave a Reply

Your email address will not be published.

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>

*

*