New-ComplianceSearchAction
This cmdlet is available in on-premises Exchange and in the cloud-based service. Some parameters and settings may be exclusive to one environment or the other.
Use the New-ComplianceSearchAction cmdlet to create actions for content searches in Exchange Server and in the Microsoft Purview compliance portal.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
New-ComplianceSearchAction
[-SearchName] <String[]>
[-Export]
[-ActionName <String>]
[-ArchiveFormat <ComplianceExportArchiveFormat>]
[-Confirm]
[-FileTypeExclusionsForUnindexedItems <String[]>]
[-EnableDedupe <Boolean>]
[-ExchangeArchiveFormat <ComplianceExportArchiveFormat>]
[-Force]
[-Format <ComplianceDataTransferFormat>]
[-IncludeCredential]
[-IncludeSharePointDocumentVersions <Boolean>]
[-JobOptions <Int32>]
[-NotifyEmail <String>]
[-NotifyEmailCC <String>]
[-ReferenceActionName <String>]
[-Region <String>]
[-Report]
[-RetentionReport]
[-RetryOnError]
[-Scenario <ComplianceSearchActionScenario>]
[-Scope <ComplianceExportScope>]
[-SearchNames <String[]>]
[-SharePointArchiveFormat <ComplianceExportArchiveFormat>]
[-ShareRootPath <String>]
[-Version <String>]
[-WhatIf]
[<CommonParameters>] New-ComplianceSearchAction
[-SearchName] <String[]>
[-Preview]
[-ActionName <String>]
[-Confirm]
[-Force]
[-Format <ComplianceDataTransferFormat>]
[-IncludeCredential]
[-JobOptions <Int32>]
[-ReferenceActionName <String>]
[-Region <String>]
[-RetryOnError]
[-Scenario <ComplianceSearchActionScenario>]
[-SearchNames <String[]>]
[-Version <String>]
[-WhatIf]
[<CommonParameters>] New-ComplianceSearchAction
[-SearchName] <String[]>
[-Purge]
[-PurgeType <ComplianceDestroyType>]
[-ActionName <String>]
[-Confirm]
[-Force]
[-Format <ComplianceDataTransferFormat>]
[-IncludeCredential]
[-JobOptions <Int32>]
[-Region <String>]
[-ReferenceActionName <String>]
[-RetryOnError]
[-Scenario <ComplianceSearchActionScenario>]
[-SearchNames <String[]>]
[-Version <String>]
[-WhatIf]
[<CommonParameters>] Description
After you create a content search using the New-ComplianceSearch cmdlet and run it using the Start-ComplianceSearch cmdlet, you assign a search action to the search using the New-ComplianceSearchAction cmdlet.
In on-premises Exchange, this cmdlet is available in the Mailbox Search role. By default, this role is assigned only to the Discovery Management role group.
You need to be assigned permissions before you can run this cmdlet. Although this topic lists all parameters for the cmdlet, you may not have access to some parameters if they're not included in the permissions assigned to you. To find the permissions required to run any cmdlet or parameter in your organization, see Find the permissions required to run any Exchange cmdlet.
In Microsoft 365, the account that you use to run this cmdlet must have a valid Microsoft 365 license assigned.
To use this cmdlet in Security & Compliance PowerShell, you need to be assigned permissions. For more information, see Permissions in the Microsoft Purview compliance portal.
Examples
Example 1
New-ComplianceSearchAction -SearchName "Project X" -PreviewThis example creates a preview search action for the content search named Project X.
Example 2
New-ComplianceSearchAction -SearchName "Project X" -ExportThis example creates an export search action for the content search named Project X.
Example 3
New-ComplianceSearchAction -SearchName "Remove Phishing Message" -Purge -PurgeType SoftDeleteThis example deletes the search results returned by a content search named Remove Phishing Message. Note that unindexed items aren't deleted when you use the Purge parameter.
Example 4
New-ComplianceSearchAction -SearchName "Case 321 All Sites" -Export -SharePointArchiveFormat SingleZip -ExchangeArchiveFormat PerUserPst -Format FxStreamThis example exports the results returned by the content search named "Case 321 All Sites". The search results are compressed and exported to a single ZIP file. If the search included any Exchange locations, the search results are exported as one PST file per mailbox.
Parameters
-ActionName
This parameter is available only in the cloud-based service.
The ActionName parameter specifies a name for the content search action. You use this parameter only when you specify multiple content searches in the SearchName parameter.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Security & Compliance |
-ArchiveFormat
This parameter has been deprecated and is no longer used.
To specify the format for Exchange search results, use the ExchangeArchiveFormat parameter. To specify the format for SharePoint and OneDrive search results, use the SharePointArchiveFormat parameter.
| Type: | ComplianceExportArchiveFormat |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Confirm
The Confirm switch specifies whether to show or hide the confirmation prompt. How this switch affects the cmdlet depends on if the cmdlet requires confirmation before proceeding.
- Destructive cmdlets (for example, Remove-* cmdlets) have a built-in pause that forces you to acknowledge the command before proceeding. For these cmdlets, you can skip the confirmation prompt by using this exact syntax:
-Confirm:$false. - Most other cmdlets (for example, New-* and Set-* cmdlets) don't have a built-in pause. For these cmdlets, specifying the Confirm switch without a value introduces a pause that forces you acknowledge the command before proceeding.
This cmdlet has a built-in pause, so use -Confirm:$false to skip the confirmation.
| Type: | SwitchParameter |
| Aliases: | cf |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-EnableDedupe
This parameter is reserved for internal Microsoft use.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Security & Compliance |
-ExchangeArchiveFormat
This parameter is functional only in the cloud-based service.
This parameter requires the Export role in Security & Compliance PowerShell. By default, this role is assigned only to the eDiscovery Manager role group.
The ExchangeArchiveFormat parameter specifies how to export Exchange search results. Valid values are:
- PerUserPst: One PST file for each mailbox.
- SinglePst: One PST file that contains all exported messages.
- SingleFolderPst: One PST file with a single root folder for the entire export.
- IndividualMessage: Export each message as an .msg message file. This is the default value.
- PerUserZip: One ZIP file for each mailbox. Each ZIP file contains the exported .msg message files from the mailbox.
- SingleZip: One ZIP file for all mailboxes. The ZIP file contains all exported .msg message files from all mailboxes. This output setting is available only in PowerShell.
To specify the format for SharePoint and OneDrive search results, use the SharePointArchiveFormat parameter.
| Type: | ComplianceExportArchiveFormat |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Export
This parameter is functional only in the cloud-based service.
This parameter requires the Export role in Security & Compliance PowerShell. By default, this role is assigned only to the eDiscovery Manager role group.
The Export switch specifies the action for the content search is to export the full set of results that match the search criteria. You don't need to specify a value with this switch.
To only return the information about each detected item in a report, use the Report switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-FileTypeExclusionsForUnindexedItems
The FileTypeExclusionsForUnindexedItems specifies the file types to exclude because they can't be indexed. You can specify multiple values separated by commas.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Force
The Force switch hides warning or confirmation messages. You don't need to specify a value with this switch.
You can use this switch to run tasks programmatically where prompting for administrative input is inappropriate.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Format
In Security & Compliance PowerShell, this parameter requires the Export role. By default, this role is assigned only to the eDiscovery Manager role group.
The Format parameter specifies the format of the search results when you use the Export switch. Valid values are:
- FxStream: Export to PST files. This is the only option that's available when you export search results from the Microsoft Purview compliance portal.
- Mime: Export to .eml message files. This the default value when you use cmdlets to export the search results.
- Msg: Export to .msg message files.
| Type: | ComplianceDataTransferFormat |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-IncludeCredential
The IncludeCredential switch specifies whether to include the credential in the results. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-IncludeSharePointDocumentVersions
This parameter is available only in the cloud-based service.
The IncludeSharePointDocumentVersions parameter specifies whether to export previous versions of the document when you use the Export switch. Valid values are:
- $true: Export all versions of the document.
- $false: Export only the current published version of the topic. This is the default value.
| Type: | Boolean |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Security & Compliance |
-JobOptions
This parameter is reserved for internal Microsoft use.
| Type: | Int32 |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-NotifyEmail
In Security & Compliance PowerShell, this parameter requires the Export role. By default, this is assigned only to the eDiscovery Manager role group.
The NotifyEmail parameter specifies the email address target for the search results when you use the Export switch.
The recipient you specify is in the To: field of the message.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-NotifyEmailCC
In Security & Compliance PowerShell, this parameter requires the Export role. By default, this role is assigned only to the eDiscovery Manager role group.
The NotifyEmailCC parameter specifies the email address target for the search results when you use the Export switch.
The recipient you specify is in the Cc: field of the message.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Preview
In Security & Compliance PowerShell, this parameter requires the Preview role. By default, this role is assigned only to the eDiscovery Manager role group.
The Preview switch specifies the action for the content search is to preview the results that match the search criteria. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Purge
Note: In Security & Compliance PowerShell, this switch is available only in the Search and Purge role. By default, this role is assigned only to the Organization Management and Data Investigator role groups.
The Purge switch specifies the action for the content search is to remove items that match the search criteria. You don't need to specify a value with this switch.
A maximum of 10 items per mailbox can be removed at one time. Because the capability to search for and remove messages is intended to be an incident-response tool, this limit helps ensure that messages are quickly removed from mailboxes. This action isn't intended to clean up user mailboxes.
Tip: To purge more than 10 items, refer to ediscoverySearch: purgeData in the Microsoft Graph API, which allows purging a maximum of 100 items per location.
You can remove items from a maximum of 50,000 mailboxes using a single content search. To remove items from more than 50,000 mailboxes, you'll have to create separate content searches. For more information, see Search for and delete email messages in your Microsoft 365 organization.
Unindexed items aren't removed from mailboxes when you use this switch.
The value of the PurgeType parameter controls how the items are removed.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-PurgeType
Note: In Security & Compliance PowerShell, this parameter is available only in the Search and Purge role. By default, this role is assigned only to the Organization Management and Data Investigator role groups.
The PurgeType parameter specifies how to remove items when the action is Purge. Valid values are:
- SoftDelete: Purged items are recoverable by users until the deleted item retention period expires.
- HardDelete (cloud only): Purged items are marked for permanent removal from the mailbox and will be permanently removed the next time the mailbox is processed by the Managed Folder Assistant. If single item recovery is enabled on the mailbox, purged items will be permanently removed after the deleted item retention period expires.
| Type: | ComplianceDestroyType |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-ReferenceActionName
This parameter is reserved for internal Microsoft use.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Region
This parameter is reserved for internal Microsoft use.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Report
This parameter is functional only in the cloud-based service.
The Report switch specifies the action for the content search is to export a report about the results (information about each item instead of the full set of results) that match the search criteria. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-RetentionReport
The RetentionReport switch specifies the action for the content search is to export a retention report. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-RetryOnError
The RetryOnError switch specifies whether to retry the action on any items that failed without re-running the entire action all over again. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Scenario
In Security & Compliance PowerShell, this parameter requires the Preview role. By default, this role is assigned only to the eDiscovery Manager role group.
The Scenario parameter specifies the scenario type when you use the Export switch. Valid values are:
- AnalyzeWithZoom: Prepare the search results for processing in Microsoft Purview eDiscovery Premium.
- General: Exports the search results to the local computer. Emails are exported to .pst files. SharePoint and OneDrive for Business documents are exported in their native Office formats.
- GenerateReportsOnly:
- Inventory:
- RetentionReports:
- TriagePreview:
| Type: | ComplianceSearchActionScenario |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-Scope
The Scope parameter specifies the items to include when the action is Export. Valid values are:
- IndexedItemsOnly
- UnindexedItemsOnly
- BothIndexedAndUnindexedItems
| Type: | ComplianceExportScope |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-SearchName
The SearchName parameter specifies the name of the existing content search to associate with the content search action. You can specify multiple content searches separated by commas.
You can find the content search by running the command Get-ComplianceSearch | Format-Table -Auto Name,Status.
| Type: | String[] |
| Position: | 1 |
| Default value: | None |
| Required: | True |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-SearchNames
This parameter is available only in the cloud-based service.
The SearchNames parameter specifies the names of the existing content searches to associate with the content search action. You separate the content search names by commas.
You can find content search names by running the command Get-ComplianceSearch | Format-Table -Auto Name,Status.
| Type: | String[] |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Security & Compliance |
-SharePointArchiveFormat
This parameter is functional only in the cloud-based service.
This parameter requires the Export role. By default, this role is assigned only to the eDiscovery Manager role group.
The SharePointArchiveFormat parameter specifies how to export SharePoint and OneDrive search results. Valid values are:
- IndividualMessage: Export the files uncompressed. This is the default value.
- PerUserZip: One ZIP file for each user. Each ZIP file contains the exported files for the user.
- SingleZip: One ZIP file for all users. The ZIP file contains all exported files from all users. This output setting is available only in PowerShell.
To specify the format for Exchange search results, use the ExchangeArchiveFormat parameter.
| Type: | ComplianceExportArchiveFormat |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-ShareRootPath
{{ Fill ShareRootPath Description }}
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019 |
-Version
This parameter is reserved for internal Microsoft use.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |
-WhatIf
The WhatIf switch doesn't work in Security & Compliance PowerShell.
The WhatIf switch simulates the actions of the command. You can use this switch to view the changes that would occur without actually applying those changes. You don't need to specify a value with this switch.
| Type: | SwitchParameter |
| Aliases: | wi |
| Position: | Named |
| Default value: | None |
| Required: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
| Applies to: | Exchange Server 2016, Exchange Server 2019, Security & Compliance |