CUT-4112: Userstate Lookups

PowerShell/JumpCloud Module/Docs/Get-JCCommand.md

@@ -187,7 +187,7 @@ Allows you to return select properties on JumpCloud user objects. Specifying wha
 Type: System.String[]
 Parameter Sets: SearchFilter
 Aliases:
-Accepted values: command, name, launchType, commandType, trigger, scheduleRepeatType
+Accepted values: command, name, launchType, commandType, trigger, scheduleRepeatType, listensTo, organization, commandRunners, schedule, shell, timeout, sudo, template, scheduleYear, timeToLiveSeconds, files, user, systems
 
 Required: False
 Position: Named

PowerShell/JumpCloud Module/Docs/Get-JCEvent.md

@@ -14,9 +14,10 @@ Query the API for Directory Insights events
 
 ### GetExpanded (Default)
 ```
-Get-JCEvent -Service <String[]> -StartTime <DateTime> [-EndTime <DateTime>] [-Fields <String[]>] [-Q <String>]
- [-SearchAfter <String[]>] [-SearchTermAnd <Hashtable>] [-SearchTermNot <Hashtable>]
- [-SearchTermOr <Hashtable>] [-Sort <String>] [-WhatIf] [-Confirm] [<CommonParameters>]
+Get-JCEvent -Service <String[]> -StartTime <DateTime> [-EndTime <DateTime>] [-Fields <String[]>]
+ [-Limit <Int64>] [-Q <String>] [-SearchAfter <String[]>] [-SearchTermAnd <Hashtable>]
+ [-SearchTermNot <Hashtable>] [-SearchTermOr <Hashtable>] [-Sort <String>] [-WhatIf] [-Confirm]
+ [<CommonParameters>]
 ```
 
 ### Get
@@ -133,6 +134,21 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -Limit
+Max number of rows to return
+
+```yaml
+Type: System.Int64
+Parameter Sets: GetExpanded
+Aliases:
+
+Required: False
+Position: Named
+Default value: 0
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### -Q
 optional string for specifying a full text query
 

PowerShell/JumpCloud Module/Docs/Get-JCScheduledUserstate.md

@@ -0,0 +1,96 @@
+---
+external help file: JumpCloud-help.xml
+Module Name: JumpCloud
+online version: https://github.com/TheJumpCloud/support/wiki/Get-JcSdkEventCount
+schema: 2.0.0
+---
+
+# Get-JCScheduledUserstate
+
+## SYNOPSIS
+Returns scheduled userstate changes by state or returns a user's scheduled userstate changes
+
+## SYNTAX
+
+### BulkLookup (Default)
+```
+Get-JCScheduledUserstate -State <String> [<CommonParameters>]
+```
+
+### ByID
+```
+Get-JCScheduledUserstate -UserId <String> [<CommonParameters>]
+```
+
+## DESCRIPTION
+Get-JCScheduledUserstate function allows for admins to view upcoming scheduled user suspensions or activations. You can also look up an individual user's upcoming state changes by their userID
+
+## EXAMPLES
+
+### Example 1
+```powershell
+Get-JCScheduledUserstate -State "SUSPENDED"
+```
+
+Returns all scheduled SUSPENDED userstate changes
+
+### Example 2
+```powershell
+Get-JCScheduledUserstate -State "ACTIVATED"
+```
+
+Returns all scheduled ACTIVATED userstate changes
+
+### Example 2
+```powershell
+Get-JCScheduledUserstate -UserID "USERID"
+```
+
+Returns all scheduled userstate changes for a given userID
+
+## PARAMETERS
+
+### -State
+The scheduled state you'd like to query (SUSPENDED or ACTIVATED)
+
+```yaml
+Type: System.String
+Parameter Sets: BulkLookup
+Aliases:
+Accepted values: SUSPENDED, ACTIVATED
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByPropertyName)
+Accept wildcard characters: False
+```
+
+### -UserId
+The _id of the User which you want to lookup.
+UserID has an Alias of _id.
+
+```yaml
+Type: System.String
+Parameter Sets: ByID
+Aliases: _id, id
+
+Required: True
+Position: Named
+Default value: None
+Accept pipeline input: True (ByPropertyName)
+Accept wildcard characters: False
+```
+
+### CommonParameters
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
+
+## INPUTS
+
+### System.String
+## OUTPUTS
+
+### System.Object
+## NOTES
+
+## RELATED LINKS

PowerShell/JumpCloud Module/Docs/Get-JCSystem.md

@@ -356,7 +356,7 @@ Valid properties that can be returned are: 'created', 'active', 'agentVersion',
 Type: System.String[]
 Parameter Sets: SearchFilter
 Aliases:
-Accepted values: acknowledged, active, agentVersion, allowMultiFactorAuthentication, allowPublicKeyAuthentication, allowSshPasswordAuthentication, allowSshRootLogin, arch, azureAdJoined, connectionHistory, created, displayName, domainInfo, fde, fileSystem, hasServiceAccount, hostname, lastContact, mdm, modifySSHDConfig, networkInterfaces, organization, os, osFamily, provisionMetadata, remoteIP, serialNumber, serviceAccountState, sshdParams, systemInsights, systemTimezone, systemToken, templateName, userMetrics, usernameHashes, version
+Accepted values: acknowledged, active, agentVersion, allowMultiFactorAuthentication, allowPublicKeyAuthentication, allowSshPasswordAuthentication, allowSshRootLogin, arch, azureAdJoined, connectionHistory, created, displayName, domainInfo, fde, fileSystem, hasServiceAccount, hostname, lastContact, mdm, modifySSHDConfig, networkInterfaces, organization, os, osFamily, provisionMetadata, remoteIP, serialNumber, serviceAccountState, sshdParams, systemInsights, systemTimezone, templateName, userMetrics, usernameHashes, version, hwVendor, secureLogin, displayManager, amazonInstanceID, archFamily, builtInCommands, description, osVersionDetail, policyStats, desktopCapable, sshRootEnabled, isPolicyBound
 
 Required: False
 Position: Named

PowerShell/JumpCloud Module/Docs/Get-JCUser.md

@@ -595,7 +595,7 @@ Valid properties that can be returned are: 'created', 'password_expiration_date'
 Type: System.String[]
 Parameter Sets: SearchFilter
 Aliases:
-Accepted values: created, password_expiration_date, account_locked, activated, addresses, allow_public_key, attributes, alternateEmail, recoveryEmail, managedAppleId, manager, email, enable_managed_uid, enable_user_portal_multifactor, externally_managed, firstname, lastname, ldap_binding_user, passwordless_sudo, password_expired, password_never_expires, phoneNumbers, samba_service_user, ssh_keys, sudo, totp_enabled, unix_guid, unix_uid, username, middlename, displayname, jobTitle, employeeIdentifier, department, costCenter, company, employeeType, description, location, external_source_type, external_dn, suspended, mfa, recoveryEmail, systemUsername
+Accepted values: created, password_expiration_date, account_locked, activated, addresses, allow_public_key, attributes, alternateEmail, recoveryEmail, managedAppleId, manager, email, enable_managed_uid, enable_user_portal_multifactor, externally_managed, firstname, lastname, ldap_binding_user, passwordless_sudo, password_expired, password_never_expires, phoneNumbers, samba_service_user, ssh_keys, sudo, totp_enabled, unix_guid, unix_uid, username, middlename, displayname, jobTitle, employeeIdentifier, department, costCenter, company, employeeType, description, location, external_source_type, external_dn, suspended, mfa, recoveryEmail, systemUsername, relationships, public_key, external_password_expiration_date, disableDeviceMaxLoginAttempts, password, state, restrictedFields
 
 Required: False
 Position: Named

PowerShell/JumpCloud Module/Docs/JumpCloud.md

@@ -2,7 +2,7 @@
 Module Name: JumpCloud
 Module Guid: 31c023d1-a901-48c4-90a3-082f91b31646
 Download Help Link: https://github.com/TheJumpCloud/support/wiki
-Help Version: 2.10.0
+Help Version: 2.11.0
 Locale: en-US
 ---
 
@@ -18,10 +18,10 @@ Create an association between two object within the JumpCloud console.
 Associates a JumpCloud system or a JumpCloud system group with a JumpCloud command
 
 ### [Add-JCGsuiteMember](Add-JCGsuiteMember.md)
-Adds users or usergroups to a GSuite Cloud Directory Instance
+Adds a user or usergroup to a GSuite instance
 
 ### [Add-JCOffice365Member](Add-JCOffice365Member.md)
-Adds users or usergroups to an Office365 Cloud Directory Instance
+Adds a user or usergroup to an Office365 instance
 
 ### [Add-JCRadiusReplyAttribute](Add-JCRadiusReplyAttribute.md)
 Adds Radius reply attributes to a JumpCloud user group.
@@ -92,6 +92,9 @@ Returns the Radius reply attributes associated with a JumpCloud user group.
 ### [Get-JCRadiusServer](Get-JCRadiusServer.md)
 Return JumpCloud radius server information.
 
+### [Get-JCScheduledUserstate](Get-JCScheduledUserstate.md)
+Returns scheduled userstate changes by state or returns a user's scheduled userstate changes
+
 ### [Get-JCSystem](Get-JCSystem.md)
 Returns all JumpCloud Systems within a JumpCloud tenant or a single JumpCloud System using the -ByID Parameter.
 
@@ -173,10 +176,10 @@ Removes a JumpCloud Command Result
 Removes the association between a JumpCloud system or a JumpCloud system group from a JumpCloud command
 
 ### [Remove-JCGsuiteMember](Remove-JCGsuiteMember.md)
-Removes users or usergroups from a GSuite Cloud Directory Instance
+Removes a user or usergroup from a GSuite instance
 
 ### [Remove-JCOffice365Member](Remove-JCOffice365Member.md)
-Removes users or usergroups from an Office365 Cloud Directory Instance
+Removes a user or usergroup from an Office365 instance
 
 ### [Remove-JCPolicy](Remove-JCPolicy.md)
 Removes a JumpCloud Policy

PowerShell/JumpCloud Module/JumpCloud.psd1

@@ -3,7 +3,7 @@
 #
 # Generated by: JumpCloud Solutions Architect Team
 #
-# Generated on: 5/30/2024
+# Generated on: 6/13/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/DefineEnvironment.ps1

@@ -84,7 +84,7 @@ $PesterParamsHash_Common = @{
     # Policy Info
     MultiplePolicyList              = @('1 Linux', 'Disable USB Storage - Linux')
     SinglePolicyList                = @('Disable USB Storage - Linux')
-    CommandResultCount              = 10
+    CommandResultCount              = 20
     SystemNameLinux                 = 'PesterTest-Linux'
     SystemNameMac                   = 'PesterTest-Mac'
     SystemNameWindows               = 'PesterTest-Windows'

PowerShell/JumpCloud Module/Tests/Public/Commands/CommandResults/Remove-JCCommandResult.Tests.ps1

@@ -8,19 +8,32 @@ Describe -Tag:('JCCommandResult') 'Remove-JCCommandResult 1.0' {
     #>
 
     It "Removes a JumpCloud command result using -CommandResultID with the force parameter" {
+        # Invoke Command to generate result
+        $SingleTrigger = Get-JCCommand | Where-Object trigger -NotLike '' | Select-Object -Last 1 | Select-Object trigger
+        $SingleResult = Invoke-JCCommand -trigger $SingleTrigger.trigger
+        Start-Sleep -Seconds 5
         $SingleCommandResult = Get-JCCommandResult | Select-Object -Last 1
         $DeletedResult = Remove-JCCommandResult -CommandResultID $SingleCommandResult._id -force
         $DeletedResult._id.count | Should -Be 1
     }
 
     It "Removes a JumpCloud command result passed through the pipeline with the force parameter without declaring -CommandResultID" {
-
+        # Invoke Command to generate result
+        $SingleTrigger = Get-JCCommand | Where-Object trigger -NotLike '' | Select-Object -Last 1 | Select-Object trigger
+        $SingleResult = Invoke-JCCommand -trigger $SingleTrigger.trigger
+        Start-Sleep -Seconds 5
         $DeletedResult = Get-JCCommandResult | Select-Object -Last 1 | Remove-JCCommandResult -force
         $DeletedResult._id.count | Should -Be 1
 
     }
 
     It "Removes two JumpCloud command results passed through the pipeline with force parameter without declaring -CommandResultID" {
+        for ($i = 0; $i -lt 2; $i++) {
+            # Invoke Command to generate result
+            $SingleTrigger = Get-JCCommand | Where-Object trigger -NotLike '' | Select-Object -Last 1 | Select-Object trigger
+            $SingleResult = Invoke-JCCommand -trigger $SingleTrigger.trigger
+        }
+        Start-Sleep -Seconds 5
         $DeletedResult = Get-JCCommandResult | Select-Object -Last 2 | Remove-JCCommandResult -force
         $DeletedResult._id.count | Should -Be 2