Find suspended users by how many days they've been suspended

[GWein]

Get-JCSuspendedUsersByDays

This function will find all suspension events in your organization that are either within the last 90 days or a specified amount of days.
It will then attempt to match all of the users whos state is `SUSPENDED` to those events and categorize them in either a `SuspendedOverDays` or `SuspendedWithinDays` group

• If a user is inside the `SuspendedOverDays` group, that means the user's event not within the bounds of the query, as an example:
  • A user was suspended 91 days ago, they will be placed in the SuspendedOverDays group
• If a user is inside the `SuspendedWithinDays` group, that means the user's event was within the bounds of the query, as an example:
  • A user was suspended 5 days ago, they will be placed in the SuspendedWithinDays group

The function will return a hashtable containing the two groups which can be used for reporting or whatever you'd like to with the user objects

@{
SuspendedOverDays = #Suspended users who exceed the bounds of the query
SuspendedWithinDays = #Suspended users who are within the bounds of the query
}

Usage Example:

# By default, the amount of days is 90
$suspendedUsers = Get-JCSuspendedUserByDays

# This group contains users that have been suspended longer than 90 days
$suspendedUsers.SuspendedOverDays

# This group contains users that have been suspended shorter than 90 days
$suspendedUsers.SuspendedWithinDays

# Using the -days Parameter, you can specify the amount of days you would like to look back
$suspendedUsers30Days = Get-JCSuspendedUsersByDays -Days 30

# This group contains users that have been suspended longer than 30 days
$suspendedUsers30Days.SuspendedOverDays

# This group contains users that have been suspended shorter than 30 days
$suspendedUsers30Days.SuspendedWithinDays

# You can create a report with this data by exporting the group to a csv
$suspendedUsers30Days.SuspendedOverDays | Export-CSV -Path '/Users/USERNAME/Documents/suspendedUsersOver30Days.csv'
$suspendedUsers30Days.SuspendedWithinDays | Export-CSV -Path '/Users/USERNAME/Documents/suspendedUsersUnder30Days.csv'

Function:

function Get-JCSuspendedUsersByDays {
    param (
        [int]$days = 90
    )
    begin {
        Write-Verbose 'Verifying JCAPI Key'
        if ($JCAPIKEY.length -ne 40) { Connect-JConline }
        $suspendedOutsideCriteriaArray = @()
        $suspendedWithinCriteriaArray = @()
    }
    process {
        $suspendedUsers = Get-JCSdkUser -Filter 'state:$eq:SUSPENDED'
        $suspensionEvents = Get-JCSdkEvent -Service:('directory') -StartTime:((Get-date).AddDays(-$days)) -SearchTermAnd @{"event_type" = "user_suspended"}
        $suspendedUsers | ForEach-Object {
            $suspendedUserID = $_.id
            $suspensionEvent = $suspensionEvents | Where-Object { $_.resource.id -eq $suspendedUserID }
            if (!$suspensionEvent) {
                $suspendedOutsideCriteriaArray += $_ | ConvertTo-Json | ConvertFrom-Json -Depth 99
            } else {
                $suspendedWithinCriteriaArray += $_ | ConvertTo-Json | ConvertFrom-Json -Depth 99 | Select-Object *, @{n="Suspension_timestamp"; e={$suspensionEvent.timestamp}}
            }
        }
    }
    end {
        return @{
            SuspendedOverDays   = $suspendedOutsideCriteriaArray
            SuspendedWithinDays = $suspendedWithinCriteriaArray
        }
    }
}