diff --git a/CHANGELOG.md b/CHANGELOG.md index 63de141..b651a66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,9 @@ All notable changes to this project will be documented in this file. ## Unreleased -- N/A +### Added + +- `Get-SIASession -session_id` gets a single session by id. Its `extra_info` steps list as a `key`, `status`, `label` table, and step details holding JSON are returned as objects. ## [0.7.0] - 2026-10-16 diff --git a/IdentityCommand.SIA/Public/Get-SIASession.ps1 b/IdentityCommand.SIA/Public/Get-SIASession.ps1 index bb101b9..9c7f4c4 100644 --- a/IdentityCommand.SIA/Public/Get-SIASession.ps1 +++ b/IdentityCommand.SIA/Public/Get-SIASession.ps1 @@ -1,18 +1,27 @@ # .ExternalHelp IdentityCommand.SIA-help.xml function Get-SIASession { - [CmdletBinding()] + [CmdletBinding(DefaultParameterSetName = 'List')] param( [parameter( Mandatory = $false, - ValueFromPipelinebyPropertyName = $true + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'List' )] [datetime]$minStartedTime, [parameter( Mandatory = $false, - ValueFromPipelinebyPropertyName = $true + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'List' )] - [datetime]$maxStartedTime + [datetime]$maxStartedTime, + + [parameter( + Mandatory = $true, + ValueFromPipelinebyPropertyName = $true, + ParameterSetName = 'ById' + )] + [String]$session_id ) begin { }#begin @@ -21,6 +30,32 @@ function Get-SIASession { $URI = "$(Resolve-RequestUrl)/api/monitoring/sessions" + if ($PSCmdlet.ParameterSetName -eq 'ById') { + + $result = Invoke-IDRestMethod -Uri "$URI/$session_id" -Method GET + + #Parse JSON details, show key/status/label by default + $DisplaySet = [System.Management.Automation.PSPropertySet]::new('DefaultDisplayPropertySet', [string[]]@('key', 'status', 'label')) + $StandardMembers = [System.Management.Automation.PSMemberInfo[]]@($DisplaySet) + + foreach ($step in $result.extra_info) { + + if ($step.details -match '^\s*[\[{]') { + try { + $step.details = $step.details | ConvertFrom-Json -ErrorAction Stop + } catch { + Write-Verbose "$($step.key) details left as text: $($_.Exception.Message)" + } + } + + $step | Add-Member -MemberType MemberSet -Name PSStandardMembers -Value $StandardMembers -Force + + } + + return $result + + } + $boundparameters = $PSBoundParameters | Get-Parameter #If no arguments initialise boundparameters diff --git a/IdentityCommand.SIA/en-US/IdentityCommand.SIA-help.xml b/IdentityCommand.SIA/en-US/IdentityCommand.SIA-help.xml index 34dc254..7fb80da 100644 --- a/IdentityCommand.SIA/en-US/IdentityCommand.SIA-help.xml +++ b/IdentityCommand.SIA/en-US/IdentityCommand.SIA-help.xml @@ -2242,6 +2242,21 @@ None + + Get-SIASession + + session_id + + The id of the session to get + + String + + String + + + None + + @@ -2270,6 +2285,18 @@ None + + session_id + + The id of the session to get + + String + + String + + + None + @@ -2307,6 +2334,23 @@ Gets session diagnostic data from the specified dates until now + + -------------------------- Example 5 -------------------------- + Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732 + + Gets the specified session + + + + -------------------------- Example 6 -------------------------- + $session = Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732 +$session.extra_info +($session.extra_info | Where-Object key -eq cms).details | Format-Table + + Lists the connection steps of the session, then shows the tunnel details for each connector as a table. + Step details holding JSON are returned as objects; other details are returned as text. + + diff --git a/Tests/Get-SIASession.Tests.ps1 b/Tests/Get-SIASession.Tests.ps1 index 214523d..5837048 100644 --- a/Tests/Get-SIASession.Tests.ps1 +++ b/Tests/Get-SIASession.Tests.ps1 @@ -1,4 +1,4 @@ -#InModuleScope below runs at discovery, so the module must be imported before then +#InModuleScope below runs at discovery, so the module must be imported before then BeforeDiscovery { $ManifestPath = Join-Path (Resolve-Path "$(Split-Path -Parent $PSCommandPath)\..\IdentityCommand.SIA") 'IdentityCommand.SIA.psd1' if ( -not (Get-Module -Name 'IdentityCommand.SIA' -All)) { @@ -177,6 +177,85 @@ Describe $($PSCommandPath -Replace '.Tests.ps1') { } + Context 'ById' { + + BeforeEach { + $response = Get-SIASession -session_id 'a93281d8-6109-dcc4-b537-67e45b41f732' + } + + It 'sends request to expected endpoint' { + + Should -Invoke -CommandName Invoke-IDRestMethod -ParameterFilter { + + $URI -eq 'https://somedomain.dpa.cyberark.cloud/api/monitoring/sessions/a93281d8-6109-dcc4-b537-67e45b41f732' + + } -Times 1 -Exactly -Scope It + + } + + It 'uses expected method' { + + Should -Invoke -CommandName Invoke-IDRestMethod -ParameterFilter { $Method -match 'GET' } -Times 1 -Exactly -Scope It + + } + + It 'accepts session_id from the pipeline' { + + [pscustomobject]@{ session_id = 'sess-1' } | Get-SIASession + + Should -Invoke -CommandName Invoke-IDRestMethod -ParameterFilter { + + $URI -eq 'https://somedomain.dpa.cyberark.cloud/api/monitoring/sessions/sess-1' + + } -Times 1 -Exactly -Scope It + + } + + It 'outputs the response' { + + $response.items | Should -Be 'value' + + } + + It 'parses JSON details and leaves text details as strings' { + + Mock Invoke-IDRestMethod -MockWith { + [pscustomobject]@{ + session_id = 'sess-1' + extra_info = @( + [pscustomobject]@{ key = 'authentication'; label = 'Authentication'; type = 'text'; status = 'success'; details = 'Authentication success'; warning_code = $null } + [pscustomobject]@{ key = 'cms'; label = 'Creating a tunnel'; type = 'text'; status = 'success'; details = '[{"Connector hostname":"CONN01","Target port":"3389"}]'; warning_code = $null } + [pscustomobject]@{ key = 'broken'; label = 'Broken'; type = 'table'; status = 'success'; details = '[not json'; warning_code = $null } + ) + } + } + + $response = Get-SIASession -session_id 'sess-1' + + $response.extra_info[0].details | Should -Be 'Authentication success' + $response.extra_info[1].details.'Connector hostname' | Should -Be 'CONN01' + $response.extra_info[2].details | Should -Be '[not json' + + } + + It 'shows key, status and label by default for extra_info steps' { + + Mock Invoke-IDRestMethod -MockWith { + [pscustomobject]@{ + extra_info = @( + [pscustomobject]@{ key = 'cms'; label = 'Creating a tunnel'; type = 'text'; status = 'success'; details = 'x'; warning_code = $null } + ) + } + } + + $response = Get-SIASession -session_id 'sess-1' + + $response.extra_info[0].PSStandardMembers.DefaultDisplayPropertySet.ReferencedPropertyNames | Should -Be @('key', 'status', 'label') + + } + + } + Context 'Output' { BeforeEach { $response = Get-SIASession diff --git a/docs/collections/_commands/Get-SIASession.md b/docs/collections/_commands/Get-SIASession.md index 648b753..fcb6028 100644 --- a/docs/collections/_commands/Get-SIASession.md +++ b/docs/collections/_commands/Get-SIASession.md @@ -12,10 +12,16 @@ Get SIA Session data ## SYNTAX +### List (Default) ``` Get-SIASession [[-minStartedTime] ] [[-maxStartedTime] ] [] ``` +### ById +``` +Get-SIASession -session_id [] +``` + ## DESCRIPTION Gets SIA session diagnostic data @@ -49,6 +55,24 @@ Get-SIASession -minStartedTime (Get-Date 01-03-2024) Gets session diagnostic data from the specified dates until now +### Example 5 +``` +Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732 +``` + +Gets the specified session + +### Example 6 +``` +$session = Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732 +$session.extra_info +($session.extra_info | Where-Object key -eq cms).details | Format-Table +``` + +Lists the connection steps of the session, then shows the tunnel details for each connector as a table. + +Step details holding JSON are returned as objects; other details are returned as text. + ## PARAMETERS ### -minStartedTime @@ -58,7 +82,7 @@ If not specified will default to 1 day before the maxStartedTime ```yaml Type: DateTime -Parameter Sets: (All) +Parameter Sets: List Aliases: Required: False @@ -75,7 +99,7 @@ If not specified, will default to now ```yaml Type: DateTime -Parameter Sets: (All) +Parameter Sets: List Aliases: Required: False @@ -85,6 +109,21 @@ Accept pipeline input: True (ByPropertyName) Accept wildcard characters: False ``` +### -session_id +The id of the session to get + +```yaml +Type: String +Parameter Sets: ById +Aliases: + +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).