Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
43 changes: 39 additions & 4 deletions IdentityCommand.SIA/Public/Get-SIASession.ps1
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -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
Expand Down
44 changes: 44 additions & 0 deletions IdentityCommand.SIA/en-US/IdentityCommand.SIA-help.xml
Original file line number Diff line number Diff line change
Expand Up @@ -2242,6 +2242,21 @@
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
<command:syntaxItem>
<maml:name>Get-SIASession</maml:name>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
<maml:name>session_id</maml:name>
<maml:description>
<maml:para>The id of the session to get</maml:para>
</maml:description>
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
<dev:type>
<maml:name>String</maml:name>
<maml:uri />
</dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
</command:syntaxItem>
</command:syntax>
<command:parameters>
<command:parameter required="false" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="1" aliases="none">
Expand Down Expand Up @@ -2270,6 +2285,18 @@
</dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
<command:parameter required="true" variableLength="true" globbing="false" pipelineInput="True (ByPropertyName)" position="named" aliases="none">
<maml:name>session_id</maml:name>
<maml:description>
<maml:para>The id of the session to get</maml:para>
</maml:description>
<command:parameterValue required="true" variableLength="false">String</command:parameterValue>
<dev:type>
<maml:name>String</maml:name>
<maml:uri />
</dev:type>
<dev:defaultValue>None</dev:defaultValue>
</command:parameter>
</command:parameters>
<command:inputTypes />
<command:returnValues />
Expand Down Expand Up @@ -2307,6 +2334,23 @@
<maml:para>Gets session diagnostic data from the specified dates until now</maml:para>
</dev:remarks>
</command:example>
<command:example>
<maml:title>-------------------------- Example 5 --------------------------</maml:title>
<dev:code>Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732</dev:code>
<dev:remarks>
<maml:para>Gets the specified session</maml:para>
</dev:remarks>
</command:example>
<command:example>
<maml:title>-------------------------- Example 6 --------------------------</maml:title>
<dev:code>$session = Get-SIASession -session_id a93281d8-6109-dcc4-b537-67e45b41f732
$session.extra_info
($session.extra_info | Where-Object key -eq cms).details | Format-Table</dev:code>
<dev:remarks>
<maml:para>Lists the connection steps of the session, then shows the tunnel details for each connector as a table.</maml:para>
<maml:para>Step details holding JSON are returned as objects; other details are returned as text.</maml:para>
</dev:remarks>
</command:example>
</command:examples>
<command:relatedLinks />
</command:command>
Expand Down
81 changes: 80 additions & 1 deletion Tests/Get-SIASession.Tests.ps1
Original file line number Diff line number Diff line change
@@ -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)) {
Expand Down Expand Up @@ -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
Expand Down
43 changes: 41 additions & 2 deletions docs/collections/_commands/Get-SIASession.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,10 +12,16 @@ Get SIA Session data

## SYNTAX

### List (Default)
```
Get-SIASession [[-minStartedTime] <DateTime>] [[-maxStartedTime] <DateTime>] [<CommonParameters>]
```

### ById
```
Get-SIASession -session_id <String> [<CommonParameters>]
```

## DESCRIPTION
Gets SIA session diagnostic data

Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -75,7 +99,7 @@ If not specified, will default to now

```yaml
Type: DateTime
Parameter Sets: (All)
Parameter Sets: List
Aliases:

Required: False
Expand All @@ -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).

Expand Down
Loading