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).