diff --git a/.circleci/workflows.yml b/.circleci/workflows.yml index 8f97ecc25..fd4ddf8a4 100755 --- a/.circleci/workflows.yml +++ b/.circleci/workflows.yml @@ -32,7 +32,7 @@ parameters: description: 'Release Type. Accepted values [ Major, Minor, Patch ]' type: enum enum: ["Major", "Minor", "Patch"] - default: "Patch" + default: "Minor" RequiredModulesRepo: description: 'PowerShell Repository for JumpCloud SDKs' type: enum @@ -45,7 +45,7 @@ parameters: PublishToPSGallery: description: 'When `true` and when run against Master branch, this workflow will publish the latest code to PSGallery' type: boolean - default: false + default: true ManualModuleVersion: description: 'When `true` the pipeline will use the Module Version specified in JumpCloud Module JumpCloud.psd1 file' type: boolean diff --git a/PowerShell/JumpCloud Module/Docs/Get-JCCommand.md b/PowerShell/JumpCloud Module/Docs/Get-JCCommand.md index 0cd9d12ab..ece9505be 100644 --- a/PowerShell/JumpCloud Module/Docs/Get-JCCommand.md +++ b/PowerShell/JumpCloud Module/Docs/Get-JCCommand.md @@ -12,9 +12,10 @@ Returns all JumpCloud Commands within a JumpCloud tenant or a single JumpCloud C ## SYNTAX -### ReturnAll (Default) +### SearchFilter (Default) ``` -Get-JCCommand [] +Get-JCCommand [-command ] [-name ] [-commandType ] [-launchType ] + [-trigger ] [-scheduleRepeatType ] [-returnProperties ] [] ``` ### ByID @@ -52,13 +53,31 @@ Note that when running this command the time for the output to display will be d ### Example 4 ```powershell -PS C:\> Get-JCCommand | Where-Object launchType -EQ 'trigger' | Get-JCCommand -ByID +PS C:\> Get-JCCommand -name '*BitLocker*' | Get-JCCommand -ByID +``` + +Returns all information describing all JumpCloud commands with a name of '*trigger*' by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note, search parameters on Get-JCCommand support wildcard characters. In this example commands with the name BitLocker somewhere in the name would be returned. + +Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. + +### Example 5 +```powershell +PS C:\> Get-JCCommand -launchType 'trigger' | Get-JCCommand -ByID ``` Returns all information describing all JumpCloud commands with a launchType of 'trigger' by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. +### Example 6 +```powershell +PS C:\> Get-JCCommand -command '*fdesetup*' | Get-JCCommand -ByID +``` + +Returns all information describing all JumpCloud commands with a command string and the search term "fdesetup", by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note, search parameters on Get-JCCommand support wildcard characters. In this example commands with the string "fdesetup" somewhere in the command body would be returned. + +Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. + ## PARAMETERS ### -ByID @@ -77,6 +96,21 @@ Accept pipeline input: False Accept wildcard characters: False ``` +### -command +The command to execute on the server. + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + ### -CommandID The _id of the JumpCloud command you wish to query. @@ -102,11 +136,107 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -commandType +Command Type + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: +Accepted values: windows, mac, linux + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -launchType +Launch Type + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: +Accepted values: repeated, one-time, manual, trigger + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -name +Name of the command + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -returnProperties +Allows you to return select properties on JumpCloud user objects. Specifying what properties are returned can drastically increase the speed of the API call with a large data set. Valid properties that can be returned are: 'command', 'name','commandType', 'launchType','listensTo','schedule','trigger','scheduleRepeatType','organization' + +```yaml +Type: System.String[] +Parameter Sets: SearchFilter +Aliases: +Accepted values: command, name, launchType, commandType, trigger, scheduleRepeatType + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -scheduleRepeatType +When the command will repeat + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: +Accepted values: minute, hour, day, week, month + +Required: False +Position: Named +Default value: None +Accept pipeline input: True (ByPropertyName) +Accept wildcard characters: False +``` + +### -trigger +The name of the command trigger + +```yaml +Type: System.String +Parameter Sets: SearchFilter +Aliases: + +Required: False +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 + ### System.String[] ## OUTPUTS diff --git a/PowerShell/JumpCloud Module/Docs/JumpCloud.md b/PowerShell/JumpCloud Module/Docs/JumpCloud.md index e7fb530d6..0d95a1d73 100644 --- a/PowerShell/JumpCloud Module/Docs/JumpCloud.md +++ b/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: 1.22.1 +Help Version: 1.23.0 Locale: en-US --- diff --git a/PowerShell/JumpCloud Module/JumpCloud.psd1 b/PowerShell/JumpCloud Module/JumpCloud.psd1 index 043c770a1..7dda14111 100755 --- a/PowerShell/JumpCloud Module/JumpCloud.psd1 +++ b/PowerShell/JumpCloud Module/JumpCloud.psd1 @@ -3,7 +3,7 @@ # # Generated by: JumpCloud Solutions Architect Team # -# Generated on: 5/19/2022 +# Generated on: 6/22/2022 # @{ @@ -12,7 +12,7 @@ RootModule = 'JumpCloud.psm1' # Version number of this module. -ModuleVersion = '1.22.1' +ModuleVersion = '1.23.0' # Supported PSEditions # CompatiblePSEditions = @() diff --git a/PowerShell/JumpCloud Module/Public/Commands/Get-JCCommand.ps1 b/PowerShell/JumpCloud Module/Public/Commands/Get-JCCommand.ps1 index 6d65b6003..03be16e3f 100644 --- a/PowerShell/JumpCloud Module/Public/Commands/Get-JCCommand.ps1 +++ b/PowerShell/JumpCloud Module/Public/Commands/Get-JCCommand.ps1 @@ -1,10 +1,29 @@ Function Get-JCCommand () { - [CmdletBinding(DefaultParameterSetName = 'ReturnAll')] + [CmdletBinding(DefaultParameterSetName = 'SearchFilter')] param ( + + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The command body text of the JumpCloud Command you wish to search for ex. Get-JCCommand -command ')] + [String]$command, + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The name of the JumpCloud Command you wish to search for ex. Get-JCCommand -name ')] + [String]$name, + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The type (windows, mac, linux) of the JumpCloud Command you wish to search for ex. Get-JCCommand -commandType ')] + [ValidateSet('windows', 'mac', 'linux')] + [string]$commandType, + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The launch type of the JumpCloud Command you wish to search for ex. Get-JCCommand -launchType ' )] + [ValidateSet('repeated','one-time','manual', 'trigger')] + [string]$launchType, + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The trigger name of the JumpCloud Command you wish to search for ex. Get-JCCommand -trigger ')] + [string]$trigger, + [Parameter( ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'The scheduled command repeat type (minute, hour, day, week, month) of the JumpCloud Command you wish to search for ex. Get-JCCommand -scheduleRepeatType ')] + [ValidateSet('minute', 'hour', 'day', 'week', 'month')] + [string]$scheduleRepeatType, + [Parameter(ValueFromPipelineByPropertyName, ParameterSetName = 'SearchFilter', HelpMessage = 'Allows you to return select properties on JumpCloud commands objects. Specifying what properties are returned can drastically increase the speed of the API call with a large data set. Valid properties that can be returned are: ''command'', ''name'',''launchType'',''commandType'',''trigger'',''scheduleRepeatType''')] + [ValidateSet('command', 'name', 'launchType', 'commandType','trigger', 'scheduleRepeatType')] + [String[]]$returnProperties, [Parameter(Mandatory, ValueFromPipelineByPropertyName, ParameterSetName = 'ByID', @@ -21,8 +40,6 @@ CommandID has an Alias of _id. This means you can leverage the PowerShell pipeli [Switch] $ByID ) - - begin { @@ -42,17 +59,23 @@ CommandID has an Alias of _id. This means you can leverage the PowerShell pipeli { $hdrs.Add('x-org-id', "$($JCOrgID)") } + Write-Verbose 'Initilizing resultsArray' - [int]$limit = '100' - Write-Debug "Setting limit to $limit" + $resultsArrayList = New-Object -TypeName System.Collections.ArrayList - Write-Debug 'Initilizing resultsArray and resultsArrayByID' - $resultsArray = @() + Write-Verbose "Parameter Set: $($PSCmdlet.ParameterSetName)" } process { + [int]$limit = '100' + Write-Verbose "Setting limit to $limit" + + [int]$skip = '0' + Write-Verbose "Setting limit to $limit" + + [int]$Counter = 0 if ($PSCmdlet.ParameterSetName -eq 'ReturnAll') @@ -61,7 +84,7 @@ CommandID has an Alias of _id. This means you can leverage the PowerShell pipeli Write-Debug 'Setting skip to zero' [int]$skip = 0 #Do not change! - while (($resultsArray).Count -ge $skip) + while (($resultsArrayList).Count -ge $skip) { $limitURL = "$JCUrlBasePath/api/commands?sort=type,_id&limit=$limit&skip=$skip" Write-Debug $limitURL @@ -70,31 +93,139 @@ CommandID has an Alias of _id. This means you can leverage the PowerShell pipeli $skip += $limit Write-Debug "Setting skip to $skip" - - $resultsArray += $results.results - $count = ($resultsArray).Count + $resultsArrayList += $results.results + $count = ($resultsArrayList).Count Write-Debug "Results count equals $count" } } - elseif ($PSCmdlet.ParameterSetName -eq 'ByID') - + + switch ($PSCmdlet.ParameterSetName) { - foreach ($uid in $CommandID) + SearchFilter + { + + while ((($resultsArrayList.Results).Count) -ge $Counter) + { + + if ($returnProperties) + { + + $Search = @{ + filter = @( + @{ + } + ) + limit = $limit + skip = $skip + fields = $returnProperties + } #Initialize search + + } + + else + { + + $Search = @{ + filter = @( + @{ + + } + ) + limit = $limit + skip = $skip + + } #Initialize search + + } + + foreach ($param in $PSBoundParameters.GetEnumerator()) + { + if ([System.Management.Automation.PSCmdlet]::CommonParameters -contains $param.key) { continue } + if ($param.value -is [Boolean]) + { + (($Search.filter).GetEnumerator()).add($param.Key, $param.value) + + continue + } + if ($param.key -eq 'returnProperties') + { + continue + } + + $Value = ($param.value).replace('*', '') + + if (($param.Value -match '.+?\*$') -and ($param.Value -match '^\*.+?')) + { + # Front and back wildcard + (($Search.filter).GetEnumerator()).add($param.Key, @{'$regex' = "$Value" }) + } + elseif ($param.Value -match '.+?\*$') + { + # Back wildcard + (($Search.filter).GetEnumerator()).add($param.Key, @{'$regex' = "^$Value" }) + } + elseif ($param.Value -match '^\*.+?') + { + # Front wild card + (($Search.filter).GetEnumerator()).add($param.Key, @{'$regex' = "$Value`$" }) + } + else + { + (($Search.filter).GetEnumerator()).add($param.Key, $Value) + } + + } # End foreach + + + $SearchJSON = $Search | ConvertTo-Json -Compress -Depth 4 + + Write-Debug $SearchJSON + + $URL = "$JCUrlBasePath/api/search/commands" + + $Results = Invoke-RestMethod -Method POST -Uri $Url -Header $hdrs -Body $SearchJSON -UserAgent:(Get-JCUserAgent) + + $null = $resultsArrayList.Add($Results) + + $Skip += $limit + + $Counter += $limit + } #End While + + } # End Search + ByID + { + foreach ($uid in $CommandID) { $URL = "$JCUrlBasePath/api/commands/$uid" Write-Debug $URL $CommandResults = Invoke-RestMethod -Method GET -Uri $URL -Headers $hdrs -UserAgent:(Get-JCUserAgent) - $resultsArray += $CommandResults + $null = $resultsArrayList.add($CommandResults) + + } + } +}# End Switch + } + end + { + switch ($PSCmdlet.ParameterSetName) + { + SearchFilter + { + return $resultsArrayList.Results | Select-Object -Property * } + ByID + { + return $resultsArrayList | Select-Object -Property * + } + } } - end +} - { - return $resultsArray - } -} \ No newline at end of file + + diff --git a/PowerShell/JumpCloud Module/Tests/Public/Commands/Get-JCCommand.tests.ps1 b/PowerShell/JumpCloud Module/Tests/Public/Commands/Get-JCCommand.tests.ps1 index c6b8d3451..5f32315f0 100755 --- a/PowerShell/JumpCloud Module/Tests/Public/Commands/Get-JCCommand.tests.ps1 +++ b/PowerShell/JumpCloud Module/Tests/Public/Commands/Get-JCCommand.tests.ps1 @@ -16,7 +16,6 @@ Describe -Tag:('JCCommand') 'Get-JCCommand 1.0' { $SingleCommand = Get-JCCommand | Select-Object -Last 1 $SingleResult = Get-JCCommand $SingleCommand._id $SingleResult._id.Count | Should -Be 1 - } It "Gets a single JumpCloud command using -ByID passed through the pipeline" { @@ -39,6 +38,36 @@ Describe -Tag:('JCCommand') 'Get-JCCommand 1.0' { $Triggers = Get-JCCommand | Where-Object trigger -ne '' $Triggers._id.Count | Should -BeGreaterThan 1 } - - } + +Describe -Tag('JCCommand') 'Get-JCCommand Search' { + BeforeAll { + Connect-JCOnline -JumpCloudApiKey:($PesterParams_ApiKey) -force | Out-Null + # Get Command3 because it does not contain a wildcard + $PesterParams_Command3 = Get-JCCommand -CommandID:($PesterParams_Command3.Id) + } + It "Searches a JumpCloud command by name" { + $Command = Get-JCCommand -name $PesterParams_Command3.name + $Command.name | Should -Be $PesterParams_Command3.name + } + It "Searches a JumpCloud command by command" { + $Command = Get-JCCommand -command $PesterParams_Command3.command + $Command.command | Should -Be $PesterParams_Command3.command + } + It "Searches a JumpCloud command by commandType" { + $Command = Get-JCCommand -commandType $PesterParams_Command3.commandType + $Command.commandType | Should -Bein $PesterParams_Command3.commandType + } + It "Searches a JumpCloud command by launchType" { + $Command = Get-JCCommand -launchType $PesterParams_Command3.launchType + $Command.launchType | Should -Bein $PesterParams_Command3.launchType + } + It "Searches a JumpCloud command by trigger" { + $Command = Get-JCCommand -trigger $PesterParams_Command3.trigger + $Command.trigger | Should -Be $PesterParams_Command3.trigger + } + It "Searches a JumpCloud command by scheduleRepeatType" { + $Command = Get-JCCommand -scheduleRepeatType $PesterParams_Command3.scheduleRepeatType + $Command.scheduleRepeatType | Should -Bein $PesterParams_Command3.scheduleRepeatType + } +} \ No newline at end of file diff --git a/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml b/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml index ad3cb65cb..85a77563c 100644 --- a/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml +++ b/PowerShell/JumpCloud Module/en-Us/JumpCloud-help.xml @@ -3481,6 +3481,119 @@ PS C:\> $BackupJcOrganizationResults.User False + + Get-JCCommand + + command + + The command to execute on the server. + + System.String + + System.String + + + None + + + commandType + + Command Type + + + windows + mac + linux + + System.String + + System.String + + + None + + + launchType + + Launch Type + + + repeated + one-time + manual + trigger + + System.String + + System.String + + + None + + + name + + Name of the command + + System.String + + System.String + + + None + + + returnProperties + + Allows you to return select properties on JumpCloud user objects. Specifying what properties are returned can drastically increase the speed of the API call with a large data set. Valid properties that can be returned are: 'command', 'name','commandType', 'launchType','listensTo','schedule','trigger','scheduleRepeatType','organization' + + + command + name + launchType + commandType + trigger + scheduleRepeatType + + System.String[] + + System.String[] + + + None + + + scheduleRepeatType + + When the command will repeat + + + minute + hour + day + week + month + + System.String + + System.String + + + None + + + trigger + + The name of the command trigger + + System.String + + System.String + + + None + + @@ -3495,6 +3608,18 @@ PS C:\> $BackupJcOrganizationResults.User False + + command + + The command to execute on the server. + + System.String + + System.String + + + None + CommandID @@ -3511,8 +3636,88 @@ PS C:\> $BackupJcOrganizationResults.User None + + commandType + + Command Type + + System.String + + System.String + + + None + + + launchType + + Launch Type + + System.String + + System.String + + + None + + + name + + Name of the command + + System.String + + System.String + + + None + + + returnProperties + + Allows you to return select properties on JumpCloud user objects. Specifying what properties are returned can drastically increase the speed of the API call with a large data set. Valid properties that can be returned are: 'command', 'name','commandType', 'launchType','listensTo','schedule','trigger','scheduleRepeatType','organization' + + System.String[] + + System.String[] + + + None + + + scheduleRepeatType + + When the command will repeat + + System.String + + System.String + + + None + + + trigger + + The name of the command trigger + + System.String + + System.String + + + None + + + + System.String + + + + + System.String[] @@ -3562,12 +3767,28 @@ PS C:\> $BackupJcOrganizationResults.User -------------------------- Example 4 -------------------------- - PS C:\> Get-JCCommand | Where-Object launchType -EQ 'trigger' | Get-JCCommand -ByID + PS C:\> Get-JCCommand -name '*BitLocker*' | Get-JCCommand -ByID + + Returns all information describing all JumpCloud commands with a name of ' trigger ' by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note, search parameters on Get-JCCommand support wildcard characters. In this example commands with the name BitLocker somewhere in the name would be returned. + Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. + + + + -------------------------- Example 5 -------------------------- + PS C:\> Get-JCCommand -launchType 'trigger' | Get-JCCommand -ByID Returns all information describing all JumpCloud commands with a launchType of 'trigger' by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. + + -------------------------- Example 6 -------------------------- + PS C:\> Get-JCCommand -command '*fdesetup*' | Get-JCCommand -ByID + + Returns all information describing all JumpCloud commands with a command string and the search term "fdesetup", by passing the -CommandID Parameter to the -ByID Parameter using the pipeline and Parameter Binding. Note, search parameters on Get-JCCommand support wildcard characters. In this example commands with the string "fdesetup" somewhere in the command body would be returned. + Note that when running this command the time for the output to display will be directly proportionate to how many JumpCloud commands you have with a launchType of 'trigger'. The command 'Get-JCCommand -ByID' runs once for every JumpCloud command within your tenant with a launchType of 'trigger'. + + diff --git a/PowerShell/ModuleBanner.md b/PowerShell/ModuleBanner.md index bb254955d..57feda7b0 100755 --- a/PowerShell/ModuleBanner.md +++ b/PowerShell/ModuleBanner.md @@ -1,17 +1,17 @@ #### Latest Version ``` -1.22.1 +1.23.0 ``` #### Banner Current ``` -* Added functionality for Set, Get, New-JCUser to Search by Email to Manager Field +* Added search endpoint functionality and parameters to Get-jCCommand ``` #### Banner Old ``` -* New parameter -recoveryemail for Set, Get, New-JCUser +* Added functionality for Set, Get, New-JCUser to Search by Email to Manager Field ``` diff --git a/PowerShell/ModuleChangelog.md b/PowerShell/ModuleChangelog.md index b348b052d..fd2750d88 100644 --- a/PowerShell/ModuleChangelog.md +++ b/PowerShell/ModuleChangelog.md @@ -1,3 +1,14 @@ +## 1.23.0 + +Release Date: June 21, 2022 + +#### RELEASE NOTES + +This release adds search endpoint functionality and new parameters to Get-JCCommand + +#### BUG FIXES: + +* N/A ## 1.22.1 Release Date: May 19, 2022