In my last post, we discussed the basics of Event-driven Retention and walked through a simple example. You can read the previous post here: https://helloitsliam.com/2021/09/15/event-driven-retention-anyone/

After writing it, I realized that I had not mentioned an essential fact about event-driven retention. When creating the event within records management, setting the query along with the date will only affect items that meet that query now, not in the future. So in my example, I used the “Compliance Asset ID” of “FILE2021“, which returned a couple of items. In the future, if I added another twenty documents and set the asset ID to the same, nothing would happen to them.

How Do We Include Newly Updated Documents within the Event?

As you know, I am a big PowerShell advocate for all administration. Whether you are managing servers locally, cloud services, or a mix of both, PowerShell is a great tool to help create reusable scripts. Event-driven retention is an area that can benefit from some scripting to meet this requirement.

The manual way of ensuring new content is picked up and retained is to create new events within records management each week, month, year, or whatever time-span you need. The downside of this, of course, is that someone needs to remember to do that and ensure it works. The records management events page will then populate with events that are, in fact, the same as the rest. Unfortunately, there is no way around this, but with PowerShell, we can at least automate the creation of the events.

Retention PowerShell

All the PowerShell commands needed are available once a connection to the Security and Compliance Center with PowerShell. To connect to the Security and Compliance Center, you can use the following syntax:

Install-Module ExchangeOnlineManagement
Import-Module ExchangeOnlineManagement
Connect-IPPSSession -UserPrincipalName user@domain.onmicrosoft.com

When prompted, enter the password plus complete any multi-factor process as needed.

Once completed, all the PowerShell commands required become available within the current session for the connected tenant. The core commands we will use are:

Our steps to create the whole process are:

  1. Create Event Type
  2. Create Retention Label
  3. Publish the Retention Label
  4. Assign the Retention Label to the specific location
  5. Set the default asset ID value
  6. Upload the required content if required
  7. Update the content with the required Retention Label
  8. Create the Event

Create an Event Type using PowerShell

New-ComplianceRetentionEventType `
    -Name "Project Closed" `
    -Comment "Project Closed"

Create a Retention Label using PowerShell

$tag = New-ComplianceTag `
    -Name "Project Termination" `
    -Comment "Project Termination" `
    -RetentionAction KeepAndDelete `
    -RetentionDuration 2555 `
    -RetentionType EventAgeInDays `
    -EventType "Project Closed"

Publish the Retention Label using PowerShell

$policy = New-RetentionCompliancePolicy `
    -Name "Project Termination Policy" `
    -Comment "Project Termination Policy" `
    -SharePointLocation "https://m365x.sharepoint.com/sites/GlobalMarketing"
New-RetentionComplianceRule `
    -Policy $policy.Id `
    -PublishComplianceTag $tag.Id

Assign the Retention Label to the specific location using PowerShell

Install-Module PnP.PowerShell
Import-Module PnP.PowerShell
Register-PnPManagementShellAccess
$label = Get-ComplanceTag `
            -Identity "Project Termination"
Connect-PnPOnline `
    -Url "https://m365x.sharepoint.com/sites/GlobalMarketing" `
    -Interactive
Set-PnPLabel `
    -List "Shared Documents" `
    -Label $label.Name `
    -SyncToItems $true
$items = Get-PnPListItems -List "Shared Documents"

Set the default asset ID value for the location (SharePoint Library) using PowerShell

Set-PnPDefaultColumnValues `
    -List "Shared Documents" `
    -Field "ComplianceAssetId" `
    -Value "ABC12345"

The key now is to upload the content required into the location. The retention can either is assigned either manually or automatically using various options such as PowerShell.

Update all items with the required retention label using PowerShell

$items = Get-PnPListItems -List "Shared Documents"
foreach($item in $items)
{
    Set-PnPListItem `
        -List "Shared Documents" `
        -Identity $item.Id `
        -Label $label.Name
}

Create the Event using PowerShell

$tag = (Get-ComplianceTag -Identity "Project Termination").Guid
$type = (Get-ComplianceRetentionEventType -Identity "Project Closed").Guid
New-ComplianceRetentionEvent `
    -Name "Project Termination Event" `
    -EventTag "$($tag)" `
    -EventType "$($type)" `
    -EventDateTime "09/12/2021" `
    -SharePointAssetIDQuery "ComplianceAssetID:ABC12345"

When executing the “New-ComplianceRetentionEvent” it may say your query is invalid; however, it saves as expected. After creating the event, you can perform a SharePoint search using the query specified within the event.

Repeating an Event using PowerShell

As you can see, repeating or executing an event again is quickly done using PowerShell. With everything in place, from the event type, label, and policy to the label and asset ID assignment, you execute the “Create Event” PowerShell as required.

$tag = (Get-ComplianceTag -Identity "Project Termination").Guid
$type = (Get-ComplianceRetentionEventType -Identity "Project Closed").Guid
New-ComplianceRetentionEvent `
    -Name "Project Termination Event" `
    -EventTag "$($tag)" `
    -EventType "$($type)" `
    -EventDateTime "09/12/2021" `
    -SharePointAssetIDQuery "ComplianceAssetID:ABC12345"