Skip to the main content.

ScriptRunner Blog

Top ten tasks for Microsoft Purview PowerShell

Table of contents



Post Featured Image

With Microsoft Purview, you understand and govern data across your entire data estate – how can you use PowerShell to leverage the full potential? Which of these ten tasks are you already managing with PowerShell?  

Top ten lists can be a bit deceptive, especially when it comes to PowerShell cmdlets simply because there are so many of them. That being said, a top ten list is great for properly introducing some of the first cmdlets you should be using. With this article, we will be exploring tasks for Microsoft Purview Compliance that we can use PowerShell to manage.


Task one: Role group membership check 

Security and least permissions are an important aspect of any Microsoft 365 service including Purview. This is the first task as it is one of the most important to execute. Administrators should audit and correct any errant permissions or role assignments that are found in their tenant. Below are some ways to check these role groups and their memberships.


# List all Role Groups

# List Members of one Role Group
Get-RoleGroupMember -Identity RecordsManagement

# List members of all Role Groups (sorted)
(Get-RoleGroup).Name | Sort Name | % {
$Members = $Null
Write-Host $_ -ForegroundColor Green
$Members = Get-RoleGroupMember -Identity $_ 
If ($Null -eq $Members) {
Write-Host 'No Members' -ForegroundColor Yellow 
} Else { 

Any results will show like so:



Task two: eDiscovery admin

Purview has two types of roles for eDiscovery that can be assigned: eDiscovery Manager and eDiscovery Administrator. 
eDiscovery Administrators is a member of the eDiscovery Manager role group and can perform the same tasks as an eDiscovery Manager can, however an administrator can also access any case in the organization. This is something the manager role simply cannot do.

Below are four cmdlets that can be used to manager users that have this role:

# Add a new admin
Add-eDiscoveryCaseAdmin -User

# List all current admins

# Remove an existing Admin (change of responsibilities)
Remove-eDiscoveryCaseAdmin -User

# Replace the current admin with new admin(s)
Update-eDiscoveryCaseAdmin -Users,


Task three: Create labels and policies

Labelling information in a Microsoft 365 tenant is an exercise that all organizations should go through even if only two labels are created (public and internal for example) as this provide protection for information that may otherwise cause issues (financial, regulatory, etc.`) if they are released to the public by accident, on purpose or hacked. Labels and Label Policies allow organizations to put a layer of protection around information as they deem necessary. First step is to figure out what layers are needed for information produced, for example, are there partner organizations to share information with, Public information released with no protection, Confidential or Highly Confidential information that might need additional protections? Lastly, a plan needs to be created for how users will be educated and instructed on how to use labels on created documents.

# List existing Labels or Label Policies

# Create new Labels and Policies
New-Label -DisplayName 'Public' -Name 'Public' -ToolTip 'Content can be shown to the Public and is NOT protected.'
New-Label -DisplayName 'Confidential' -Name 'Confidential' -ToolTip 'Content is Confidential and for Internal User ONLY!'
New-LabelPolicy -Name 'Corporate Labels' -Labels 'Public,Confidential'

# Removing Label Policies (not labels!)
Remove-LabelPolicy -Name 'Corporate Labels'


Task four: Create compliance cases

Purview allows Compliance Administrators to perform tasks related to data discovery such as Data Subject Requests, eDiscovery, Data Investigations and more. If an organization has enough depth, Purview also allows for granularization of permissions where we can set up RBAC where users may have full access to all cases, access to certain cases or just access to results/read only views. PowerShell can be used to create cases, change permissions, pull data and more in a programmatic way. 

Below are just a small sampling of what can be done with Compliance Cases and PowerShell:

# List all Compliance Cases or filter for specific types
Get-ComplianceCase -CaseType DSR

# Create new Compliance Cases
New-ComplianceCase -Name "Case # FG-4576" -Description "Legal Case for Financial Group 05-2023"

# Add members to an existing case
Add-ComplianceCaseMember -Case "Case # 430" -Member
Add-ComplianceCaseMember -Case "Case # 430" -Member

# Remove an existing case (or all cases of a particular type)
Remove-ComplianceCase -Identity 'Case #FG-4576'
Get-ComplianceCase -CaseType DSR | Remove-ComplianceCase


Task five: Create retention policies

Retention Policies in Microsoft 365 can be applied to a myriad of data sources, ranging from Exchange mailbox data to Microsoft 365 Groups, Teams Chat/Channel Messages and even SharePoint/OneDrive data. These policies can be maintained with PowerShell by creating new ones, modifying existing ones or simply auditing what is present for reporting purposes. Microsoft provides a total of 31 cmdlets that work with retaining information in the cloud. When creating Retention Holds, it is necessary to remember that we need both a Policy (first) as well as a Rule (second). Below we have some example cmdlets on how to approach Retention in Microsoft 365:

# List any existing Retention Policies or Rules

# Create new Retention Policies and Rules
New-RetentionCompliancePolicy -Name "Seven Year Email Policy" -ExchangeLocation All
New-RetentionComplianceRule -Name "Seven Year Email Rule" -Policy "Seven Year Email Policy" -RetentionDuration 2555

# Remove Policies and Rules
Remove-RetentionCompliancePolicy -Name "Seven Year Email Policy"
Remove-RetentionComplianceRule -Name "Seven Year Email Rule" 


Note: Some settings cannot be changed once a Retention Policy has been created so be sure in your settings as a new Policy may be needed depending on the required change/update to a Policy.


Task six: Manage DLP policies & rules

Data leakage and exfiltration are common problems that administrators deal with. Microsoft's DLP (Data Loss Prevention) feature in their cloud service helps to prevent these issues for organizations. We can set policies for data in various workloads like SharePoint, Exchange, OneDrive and Teams. Similarly to the Retention Policies / Rules above, we can also manage DLP Policies and Rules with PowerShell. Here are some sample cmdlets to perform these tasks.

# List any existing Policies or Rules

# Create a new Policy and Rule Set
New-DlpCompliancePolicy -Name 'Corporate DLP Policy' -ExchangeLocation All -SharePointLocation All -TeamsLocation All -Mode TestWithNotifications
New-DlpComplianceRule -Name 'Corporate DLP Rule' -Policy 'Corporate DLP Policy' -ContentContainsSensitiveInformation @(@{Name="U.S. Social Security Number (SSN)"},@{Name="U.S. Bank Account Number"}) -BlockAccess $True

# Remove any existing Policies or Rules
Remove-DlpComplianceRule 'Corporate DLP Rule'
Remove-DlpCompliancePolicy 'Corporate DLP Policy'


Task seven: Create inside risk policies

Inside Risk Management in Microsoft 365 is meant to mitigate the risk of internal users to an organization when their actions could cause potential harm to the organization. While administrators tend to focus on external threats, this feature helps administrators also monitor internal activity for malicious or non-policy conforming activities. These activities range from: Leaks of sensitive data and data spillage, Confidentiality violations, Intellectual property (IP) theft, Fraud, Insider trading and Regulatory compliance violations. As with any feature like this, a pilot group should be formed to test out the feature to see if it is capable of performing the level of monitoring that an organization desires. Insider Risk does provide notices, reporting and affected users. Below are some of the ways we can use PowerShell to manage this feature:

# List all existing Insider Risk Policies
Get-InsiderRiskPolicy CheckForLeaks

# Create a new Insider Risk Policy
New-InsiderRiskPolicy -Name CheckForLeaks -InsiderRiskScenario LeakOfInformation

# Remove an existing Insider Risk Policy
Remove-InsiderRiskPolicy CheckForLeaks

# Change settings on an existing Insider Risk Policy
Set-InsiderRiskPolicy CheckForLeaks -AddExchangeLocation Brian

# Disable an existing Insider Risk Policy
Set-InsiderRiskPolicy CheckForLeaks -Enabled $False


Task eight: Create communication compliance policies

Monitoring communications is sometimes a necessary evil for an organization and organizations need to be aware of privacy and other regulatory rules prior to configuring any Communication Compliance Policies. Communication Compliance is a replacement for what was originally known as Supervision and is structured to monitor communications in a tenant for inappropriate communicates and can detect, capture and act on these messages. The product has pre-defined policies to help get started with the product and even allows for custom policies that you can use to scan internal and external communications. IF any messages are detected by these policies, a Reviewer can investigate and take action to make sure that communications remain compliance with your organizations policies. These messages can include emails, Microsoft Teams, Yammer or other third-party communications in your tenant. Below are some sample usages of PowerShell and Communication Compliance:

# List current Policies or Rules

# Communication Compliance Reporting

# Create new Policies and Rules
New-SupervisoryReviewPolicyV2 -Name "Source Code Detection" -Reviewers -Comment "Monitor Source Code in communications"
New-SupervisoryReviewRule -SamplingRate 50 -Policy "Source Code Detection" -Condition



Task nine: Information barriers

Information Barriers are a logical construct that prevents communication between groups of people. Any of the people that are blocked from communicating need to be synced to Azure AD. The filters for users are based off of Azure AD users and the attributes that are allowed for filters. We can use one or more filters for filtering users. However, Microsoft recommends that these filters are not too complex. When it comes to management of these barriers, we need to look to either using the Purview Compliance Center or the Security and Compliance Center PowerShell module. Below are some sample PowerShell cmdlets for Information Barriers:

# List any existing Information Barrier

# Checks Information Barrier information between Damian and Dave
Get-InformationBarrierRecipientStatus -Identity Damian -Identity2 Dave

# Create a new Information Barrier Policy
New-OrganizationSegment IT
New-OrganizationSegment Research
New-InformationBarrierPolicy -Name 'IT-Research' -AssignedSegment IT -SegmentsBlocked Research -State Active

# Change settings on an existing Information Barrier Policy
Set-InformationBarrierPolicy -Identity 'IT-Research' -State Inactive

# Remove an existing Information Barrier Policy
Remove-InformationBarrierPolicy -Identity 'IT-Research'


Note: To remove an information Barrier policy, make sure to set it to an Inactive state first.


Task ten: Microsoft analysis script

Microsoft provides a script to help with review and analysis of your Purview Compliance Center's configuration. It isn't as technical in orientation as the ORECA script that is also provided by Microsoft, but it is worth running anyway. 

Make sure to check out this link for more information and to download the script.



With PowerShell organizations are able to perform tasks needed to manage, monitor and configure the Microsoft 365 tenant and the Purview feature also allows quite a bit of control via PowerShell. In this article we focused on the top ten tasks for your Purview Compliance configuration and provided dozens of PowerShell example one-liners focused on these tasks. We hope the takeaway is that PowerShell can perform these tasks and provide time savings with proper investment by administrators. While there are certainly hundreds more cmdlets, these examples should give you the confidence to learn even more about PowerShell for Purview.




Your ultimate PowerShell cheat sheet

Unleash the full potential of PowerShell with our handy poster. Whether you're a beginner or a seasoned pro, this cheat sheet is designed to be your go-to resource for the most important and commonly used cmdlets.

The poster is available for download and in paper form.

PowerShell Poster 2023


Get your poster here!



Related links

Related posts

6 min read

Managing Microsoft Exchange with PowerShell

3 min read

Automate your spring cleaning with PowerShell

About the author: