CUT-4112: Userstate Lookups

PowerShell/JumpCloud Module/JumpCloud.psd1

@@ -3,7 +3,7 @@
 #
 # Generated by: JumpCloud Solutions Architect Team
 #
-# Generated on: 5/30/2024
+# Generated on: 6/12/2024
 #
 
 @{
@@ -12,7 +12,7 @@
     RootModule        = 'JumpCloud.psm1'
 
     # Version number of this module.
-    ModuleVersion     = '2.10.2'
+    ModuleVersion     = '2.11.0'
 
     # Supported PSEditions
     # CompatiblePSEditions = @()
@@ -80,7 +80,7 @@
     'Get-JCCommandTarget', 'Get-JCEvent', 'Get-JCEventCount', 'Get-JCGroup',
     'Get-JCOrganization', 'Get-JCPolicy', 'Get-JCPolicyResult',
     'Get-JCPolicyTargetGroup', 'Get-JCPolicyTargetSystem',
-    'Get-JCRadiusReplyAttribute', 'Get-JCRadiusServer', 'Get-JCSystem',
+    'Get-JCRadiusReplyAttribute', 'Get-JCRadiusServer', 'Get-JCScheduledUserstate', 'Get-JCSystem',
     'Get-JCSystemApp', 'Get-JCSystemGroupMember', 'Get-JCSystemInsights',
     'Get-JCSystemUser', 'Get-JCUser', 'Get-JCUserGroupMember',
     'Import-JCCommand', 'Import-JCMSPFromCSV', 'Import-JCUsersFromCSV',

PowerShell/JumpCloud Module/Public/DirectoryInsights/Get-JCEvent.ps1

@@ -100,6 +100,12 @@ Function Get-JCEvent
     # optional list of fields to return from query
     ${Fields},
 
+    [Parameter(ParameterSetName='GetExpanded')]
+    [JumpCloud.SDK.DirectoryInsights.Category('Body')]
+    [System.Int64]
+    # Max number of rows to return
+    ${Limit},
+
     [Parameter(ParameterSetName='GetExpanded')]
     [JumpCloud.SDK.DirectoryInsights.Category('Body')]
     [System.String]

PowerShell/JumpCloud Module/Public/Users/Get-JCScheduledUserstate.ps1

@@ -0,0 +1,97 @@
+Function Get-JCScheduledUserstate () {
+    [CmdletBinding(DefaultParameterSetName = 'BulkLookup')]
+    param (
+        [Parameter(Mandatory, ParameterSetName = 'BulkLookup', ValueFromPipelineByPropertyName = $True, HelpMessage = "The scheduled state you'd like to query (SUSPENDED or ACTIVATED)")]
+        [ValidateSet('SUSPENDED', 'ACTIVATED')]
+        [string]$State,
+        [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = 'ByID', HelpMessage = 'The _id of the User which you want to lookup. UserID has an Alias of _id.')]
+        [Alias('_id', 'id')]
+        [String]$UserId
+    )
+    begin {
+        Write-Verbose 'Verifying JCAPI Key'
+        if ($JCAPIKEY.length -ne 40) {
+            Connect-JCOnline
+        }
+
+        Write-Verbose 'Initilizing resultsArray'
+        $resultsArrayList = New-Object -TypeName System.Collections.ArrayList
+
+        Write-Verbose "Parameter Set: $($PSCmdlet.ParameterSetName)"
+    }
+    process {
+        switch ($PSCmdlet.ParameterSetName) {
+            BulkLookup {
+                if ($state -eq 'SUSPENDED') {
+                    $scheduledUsers = Get-JcSdkBulkUserState | Where-Object State -EQ 'SUSPENDED'
+                } else {
+                    $scheduledUsers = Get-JcSdkBulkUserState | Where-Object State -EQ 'ACTIVATED'
+                }
+
+                # If no results are found, return null
+                if (!$scheduledUsers) {
+                    return $null
+                }
+
+                # Create SearchBody to parse users
+                $searchUserBody = @{
+                    filter = @{
+                        or = @(
+                        )
+                    }
+                    fields = "firstname lastname email username _id"
+                }
+
+                # Create OR lookup for IDs
+                $scheduledUsers | ForEach-Object {
+                    $searchUserBody.filter.or += "_id:`$eq:$($_.SystemUserId)"
+                }
+
+                # Get users
+                $searchUsers = Search-JcSdkUser -Body $searchUserBody
+                $searchUsers | ForEach-Object {
+                    # Get the scheduled date for the user
+                    $user = $scheduledUsers | Where-Object SystemUserID -EQ $_.Id
+                    # Convert the scheduled date to datetime (also seems to convert to local as well)
+                    $localScheduledDate = [datetime]$user.ScheduledDate
+                    # Create userResult
+                    $userResult = [pscustomobject]@{
+                        id            = $_.Id
+                        Firstname     = $_.Firstname
+                        Lastname      = $_.Lastname
+                        Email         = $_.email
+                        Username      = $_.username
+                        State         = $State
+                        ScheduledDate = $localScheduledDate
+                    }
+                    $resultsArrayList.Add($userResult) | Out-Null
+                }
+            }
+            ByID {
+                # Get User's scheduled state
+                $scheduledUser = Get-JcSdkBulkUserState -Userid $userId
+                # User attribute lookup
+                $user = Get-JcSdkUser -Id $userId | Select-Object firstname, lastname, email, username, id
+
+                $scheduledUser | ForEach-Object {
+                    # Convert date to local
+                    $localScheduledDate = [datetime]$_.ScheduledDate
+                    # Create custom return object
+                    $userResult = [pscustomobject]@{
+                        id            = $user.Id
+                        Firstname     = $user.Firstname
+                        Lastname      = $user.Lastname
+                        Email         = $user.email
+                        Username      = $user.username
+                        State         = $_.State
+                        ScheduledDate = $LocalScheduledDate
+                    }
+                    $resultsArrayList.Add($userResult) | Out-Null
+                }
+            }
+        }
+    }
+    end {
+        return $resultsArrayList
+    }
+}

PowerShell/JumpCloud Module/Tests/Public/Users/Get-JCScheduledUserstate.Tests.ps1

@@ -0,0 +1,60 @@
+Describe -Tag:('JCScheduledUserstate') 'Get-JCScheduledUserstate' {
+    BeforeAll {
+        # Create a few users to test suspension and activation
+        $NewStateUser1 = New-RandomUser -domain "delNewUser.$(New-RandomString -NumberOfChars 5)" | New-JCUser
+        $NewStateUser2 = New-RandomUser -domain "delNewUser.$(New-RandomString -NumberOfChars 5)" | New-JCUser
+        $NewStateUser3 = New-RandomUser -domain "delNewUser.$(New-RandomString -NumberOfChars 5)" | New-JCUser -state "SUSPENDED"
+
+        $ScheduledSuspension = New-JcSdkBulkUserState -UserIds @($($NewStateUser1.Id), $($NewStateUser2.Id)) -State 'SUSPENDED' -StartDate (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+        $ScheduledActivation = New-JcSdkBulkUserState -UserIds $NewStateUser3.Id -State 'ACTIVATED' -StartDate (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+    }
+    It "Gets scheduled SUSPENDED users" {
+        $scheduledUsers = Get-JCScheduledUserstate -State "SUSPENDED"
+        $scheduledUsers.count | Should -Be 2
+
+        $scheduledUsers.id | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Firstname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Lastname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Email | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Username | Should -Not -BeNullOrEmpty
+        $scheduledUsers.ScheduledDate | Select-Object -First 1 | Should -Be (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+    }
+    It "Gets scheduled ACTIVATED users" {
+        $scheduledUsers = Get-JCScheduledUserstate -State "ACTIVATED"
+        $scheduledUsers.count | Should -Be 1
+
+        $scheduledUsers.id | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Firstname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Lastname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Email | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Username | Should -Not -BeNullOrEmpty
+        $scheduledUsers.ScheduledDate | Should -Be (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+    }
+    It "Gets scheduled user by ID" {
+        $scheduledUsers = Get-JCScheduledUserstate -UserID $NewStateUser1.Id
+
+        $scheduledUsers.id | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Firstname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Lastname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Email | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Username | Should -Not -BeNullOrEmpty
+        $scheduledUsers.ScheduledDate | Should -Be (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+    }
+    It "Gets scheduled user by ID with 2 userstate changes" {
+        $NewScheduledSuspension = New-JcSdkBulkUserState -UserIds $NewStateUser3.Id -State 'SUSPENDED' -StartDate (Get-Date -Hour 12 -Minute 0 -Second 0 -Millisecond 0).AddDays(1)
+        $scheduledUsers = Get-JCScheduledUserstate -UserID $NewStateUser3.Id
+        $scheduledUsers.count | Should -Be 2
+
+        $scheduledUsers.id | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Firstname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Lastname | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Email | Should -Not -BeNullOrEmpty
+        $scheduledUsers.Username | Should -Not -BeNullOrEmpty
+        $scheduledUsers.ScheduledDate | Should -Not -BeNullOrEmpty
+    }
+    AfterAll {
+        Remove-JCUser -UserID $NewStateUser1.Id -ByID -force
+        Remove-JCUser -UserID $NewStateUser2.Id -ByID -force
+        Remove-JCUser -UserID $NewStateUser3.Id -ByID -force
+    }
+}

PowerShell/ModuleChangelog.md

@@ -1,3 +1,18 @@
+## 2.11.0
+
+Release Date: June 12, 2024
+
+#### RELEASE NOTES
+
+```
+Introducing a new function Get-JcScheduledUserstate - This will allow for the lookup of upcoming user suspensions/activations
+```
+
+#### FEATURES:
+
+New Function: `Get-JcScheduledUserState` - Allows for the lookup of scheduled userstate changes. This will list upcoming suspensions or activations as well as being able to search for a particular user's upcoming state changes by their UserID
+
+
 ## 2.10.2
 
 Release Date: May 30, 2024