Public/Invoke-EvaluateSessionRelevance.ps1
|
function Invoke-EvaluateSessionRelevance { <# .Synopsis Evaluates Session Relevance statements. .Description Evaluates Session Relevance statements on the established Web Reports Session, parsing results into a more PowerShell-friendly format. Relevance Statements can be provided via the -Relevance parameter or the pipeline. Results are returned only after all Relevance Statements have completed. .Parameter Relevance Specifies the Session Relevance statement to evaluate on the Web Reports Session. .Parameter Session Specifies the Web Reports Session to evaluate the relevance on. If not provided, will attempt to use the last Web Reports Session created via New-WebReportsSession. .Parameter FieldNames Specifies a listing of field names to translate the evaluation tuple results into. .Example # Evaluate the Session Relevance statement 'number of bes computers'. Invoke-EvaluateSessionRelevance -Relevance 'number of bes computers' .Example # Evaluate the Session Relevance statement '(id of it, (if (exists name of it) then (name of it) # else ("<not reported>")) of it) of bes computers', parsing results into objects with the field # names 'Id' and 'Name'. Invoke-EvaluateSessionRelevance -Relevance '(id of it, (if (exists name of it) then (name of it) else ("<not reported>")) of it) of bes computers' -FieldNames @('Id', 'Name') #> [CmdLetBinding()] [OutputType('BigFix.SessionRelevanceResult')] Param( [Parameter( Mandatory = $true, Position = 0, ValueFromPipeline = $true, HelpMessage = 'Session Relevance statement to evaluate' )] [ValidateNotNullOrEmpty()] [string]$Relevance, [Parameter( Mandatory = $false, HelpMessage = 'Web Reports Session to perform the evaluation in' )] [ValidateNotNull()] [PSTypeName('BigFix.WebReports.Session')]$Session = (Get-WebReportsSession), [Parameter( Mandatory = $false, HelpMessage = 'Array of strings representing the names for each resultant tuple field' )] [string[]]$FieldNames = $null ) Begin { if ($null -eq $Session) { throw "Cannot validate argument on parameter 'Session'. The argument is null. Call New-WebReportsSession first or provide a valid value for the argument, and then try running the command again." } if ($Session.State -ne 'Connected' -and $Session.State -ne 'Connecting') { $Session.Connect() } if ($Session.State -eq 'Connecting' -or $null -eq $Session.SessionToken) { $header = New-Object "$($Session.Service.GetType().Namespace).LoginHeader" $header.username = $Session.Credential.UserName $header.password = $Session.Credential.GetNetworkCredential().Password } else { $header = New-Object "$($Session.Service.GetType().Namespace).AuthenticateHeader" $header.username = $Session.Credential.UserName $header.sessionToken = $Session.SessionToken } $Session.Service.RequestHeaderElement = $header } Process { $result = [PSCustomObject]@{ PSTypeName = 'BigFix.SessionRelevanceResult' Relevance = $Relevance Results = $null Error = $null Time = $null EvaluationTime = $null } $timer = [System.Diagnostics.Stopwatch]::StartNew() try { Write-Verbose -Message "Evaluating Relevance: $Relevance" $structuredResult = $Session.Service.GetStructuredRelevanceResult($Relevance) $result.EvaluationTime = $structuredResult.evaltime if ($structuredResult.error) { $result.Error = $structuredResult.error } else { $result.Results = Expand-StructuredRelevanceResult -InputObject $structuredResult -FieldNames $FieldNames } } catch { $result.Error = $PSItem.ToString() $Session.State = 'Error' } finally { $null = $timer.Stop() $result.Time = $timer.Elapsed if ($result.Error) { Write-Verbose -Message "Evaluation failed: $($result.Error)" } else { $Session.SessionToken = $Session.Service.ResponseHeaderElement.sessionToken Write-Verbose -Message "Evaluation produced $($result.Results.Count.ToString('N0')) answer(s) in $($result.Time)." } } return $result } } |