Check-PurviewConfig
This cmdlet is available only in Security & Compliance PowerShell. For more information, see Security & Compliance PowerShell.
Use the Check-PurviewConfig cmdlet to validate and review your organization's configuration settings in Microsoft Purview.
For information about the parameter sets in the Syntax section below, see Exchange cmdlet syntax.
Syntax
Default (Default)
Check-PurviewConfig
[[-Component] <PurviewConfigComponent>]
[[-DateTimeUTC] <String>]
[[-File] <String>]
[[-IncidentId] <String>]
[[-ItemId] <String>]
[[-MessageId] <String>]
[[-RecordId] <String>]
[[-RuleName] <String>]
[[-TestCases] <String[]>]
[[-Theme] <PurviewConfigTheme>]
[[-UserPrincipalName] <SmtpAddress>]
[[-Workload] <String>]
[-Confirm]
[-WhatIf]
[<CommonParameters>]
Description
Use the Check-PurviewConfig cmdlet to run Microsoft Information Protection diagnostic test cases for your organization and check the results.
Admins with the Organization Configuration role assigned have the necessary permissions to run this cmdlet.
To learn more about administrator role permissions in Microsoft Entra ID, see Role template IDs.
Important
Microsoft recommends that you use roles with the fewest permissions. Using lower permissioned accounts helps improve security for your organization. Global Administrator is a highly privileged role that should be limited to emergency scenarios when you can't use an existing role.
Examples
Example 1
Check-PurviewConfig
This example runs all Microsoft Information Protection test cases that don't require additional parameters.
Example 2
Check-PurviewConfig -Component Encryption
This example runs all test cases for the Encryption component.
Example 3
Check-PurviewConfig -Component Encryption -Theme LicenseAvailability
This example runs all cases for the LicenseAvailability theme in the Encryption component.
Example 4
Check-PurviewConfig -TestCases "MipLabels_EnabledEntities_ScopedLabels" -UserPrincipalName sathya@contoso.onmicrosoft.com
This example runs the test case named MipLabels_EnabledEntities_ScopedLabels, which requires a UserPrincipalName value.
Example 5
Check-PurviewConfig -TestCases "MipLabels_EnabledEntities_ScopedLabels","MipLabels_EnabledEntities_CompareSyncStatus" -UserPrincipalName sathya@contoso.onmicrosoft.com
This example runs the specified test cases. A UserPrincipalName value is required for the MipLabels_EnabledEntities_ScopedLabels test case.
Parameters
-Component
Applicable: Security & Compliance
The Component parameter specifies the component to analyze in the test case. Valid values are:
- DLP
- DLPAlerts
- Encryption
- MIPLabels
Parameter properties
| Type: | PurviewConfigComponent |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Confirm
Applicable: Security & Compliance
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.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | cf |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DateTimeUTC
Applicable: Security & Compliance
The DateTimeUTC specifies the date-time of the test case in Coordinated Universal Time (UTC). For example, "2025-06-05 14:30:00".
This parameter is required for the following TestCases values:
- DlpAlerts_CheckAlertsCreated
- DlpAlerts_FindAlertForActivity
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-File
Applicable: Security & Compliance
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 2 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-IncidentId
Applicable: Security & Compliance
The IncidentId parameter specifies the incident to analyze in the test case.
You can find a value for this parameter in audit log searches filtered by the operation DLPRuleMatch in the IncidentId property.
This parameter is required for the TestCases value DlpAlerts_FindAlertForActivity.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 3 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ItemId
Applicable: Security & Compliance
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 4 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-MessageId
Applicable: Security & Compliance
This parameter is reserved for internal Microsoft use.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 5 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RecordId
Applicable: Security & Compliance
The RuleName parameter specifies the record to analyze in the test case.
You can find a value for this parameter in Activity Explorer filtered by the activity type DLPRuleMatch in the RecordId property.
This parameter is optional with the TestCases value DlpAlerts_FindAlertForActivity.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 6 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-RuleName
Applicable: Security & Compliance
The RuleName parameter specifies the DLP rule to analyze in the test case.
This parameter is optional with the TestCases value DlpAlerts_CheckAlertsCreated.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 7 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-TestCases
Applicable: Security & Compliance
The TestCases parameter specifies the name of the test case to analyze. The available test cases and their required parameters are described in the following list:
- Encryption_EvaluationDetails: Validates email encryption evaluation details. No other parameters are required.
- Encryption_LicenseAvailability: Checks email encryption configurations. No other parameters are required.
- MipLabels_EnabledEntities_ScopedLabels: Shows the labels and label settings that apply to a user. Requires the UserPrincipalName parameter.
- MipLabels_LicenseAvailability: Verifies whether the MIP Label feature is enabled. No other parameters required.
- DlpAlerts_CheckAlertsCreated: Validates the DLP rule configuration for alerts created in last 5 days. Requires the DateTimeUTC parameter. The RuleName parameter is optional.
- DlpAlerts_FindAlertForActivity: Identifies missing alerts for an activity. Requires the DateTimeUTC parameter. The IncidentId and RecordId parameters are optional.
- DLP_ScopedEntities: Returns all DLP policies and rules that apply to a user or a site. Requires the Workload parameter. The SiteUrl and UserPrincipalName parameters are optional.
You can specify multiple values separated by commas.
Parameter properties
| Type: | String[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 8 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Theme
Applicable: Security & Compliance
The Theme parameter filters specifies the them to analyze in the test case. Valid values are:
- EnabledEntities
- EvaluationDetails
- LicenseAvailability
Parameter properties
| Type: | PurviewConfigTheme |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 9 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-UserPrincipalName
Applicable: Security & Compliance
The UserPrincipalName parameter specifies the user account to analyze in the test case (for example, sathya@contoso.onmicrosoft.com).
- Required for the TestCases value MipLabels_EnabledEntities_ScopedLabels.
- Optional for the TestCases value DLP_ScopedEntities.
Parameter properties
| Type: | SmtpAddress |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 10 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-WhatIf
Applicable: Security & Compliance
The WhatIf switch doesn't work in Security & Compliance PowerShell.
Parameter properties
| Type: | SwitchParameter |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
| Aliases: | wi |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Workload
Applicable: Security & Compliance
The Workload parameter specifies the service workload. Value values are:
- EndpointDevices
- Exchange
- OneDriveForBusiness
- SharePoint
- Teams
This parameter is required for the TestCases value DLP_ScopedEntities.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 11 |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.