Nectar10

4.30

Functions/Public/EPCTestPoint.ps1

Function Get-EPCTestPoint {
    <#
        .SYNOPSIS
        Return information about a given EPC test point
         
        .DESCRIPTION
        Return information about a given EPC test point
         
        .PARAMETER Name
        The name of a specific test point to retrieve information about. Will do partial matches.
     
        .PARAMETER Status
        Only return information about test points with a specified status
         
        .PARAMETER OrgID
        Only return information about test points within a specified organization
         
        .PARAMETER Version
        Only return information about test points that match the given version
         
        .PARAMETER RGName
        Only return information about test points that are within a given resource group
        Can specify either RG name or ID
 
        .PARAMETER RGID
        Only return information about test points that are within a given resource group
        Can specify either RG name or ID
         
        .PARAMETER ResultSize
        The number of results to return. Defaults to 1000.
 
        .EXAMPLE
        Get-EPCTestPoint
        Returns information about the first 10000 test points
 
        .EXAMPLE
        Get-EPCTestPoint -Name 'TFerguson Laptop'
        Returns information about a specific test point using the test point name
         
        .EXAMPLE
        Get-EPCTestPoint -Status Connected -OrgID Contoso
        Returns information about connected test points in the Contoso organization
 
        .NOTES
        Version 1.0
    #>
    
    [cmdletbinding()]
    Param (
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [Alias('EndpointName')]
        [string]$Name,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [ValidateSet('Connected','NotConnected','Reachable','Unknown','Unlicensed', IgnoreCase=$True)]
        [string]$Status,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [string]$OrgID,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [string]$Version,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [string]$RGName,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [int[]]$RGID,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [bool]$IncludeHubResourceUsage = $False,
        [Parameter(Mandatory=$False)]
        [int]$ResultSize = 10000,
        [switch]$UseXML
    )
    
    Begin {
        Connect-EPCController
        
        If ($Global:EPC_UseWSDL -And $UseXML -eq $False) {
            $EPCCred = New-Object -TypeName EPC.ActiveCtrl.CredentialsType
            $EPCCred.username = $Global:EPControllerCred.UserName
            $EPCCred.password = $Global:EPControllerCred.GetNetworkCredential().Password
        }
        Else {
            $ProgressPreference = 'SilentlyContinue'
        }
    }
    Process {
        If ($Global:EPC_UseWSDL -And $UseXML -eq $False) {
            Write-Verbose 'Using WSDL'
            $EPCListTestPointParams = New-Object -TypeName EPC.ActiveCtrl.ListTestPointsParametersType
            $EPCListTestPointParams.credentials = $EPCCred 
            $EPCListTestPointParams.maxNumber = $ResultSize
            $EPCListTestPointParams.includeHubResourceUsage = $IncludeHubResourceUsage

            # If any of the below parameters are specified, apply a filter
            If ($Name -Or $Status -Or $OrgID -Or $Version -Or $RGName -Or $RGID) {
                $EPCListTestPointFilterParams = New-Object -TypeName EPC.ActiveCtrl.ListTestPointsParametersTypeFilter
                If ($Name) { $EPCListTestPointFilterParams.namesubstring = $Name }
                If ($OrgID) { $EPCListTestPointFilterParams.orgID = $OrgID }
                If ($Version) { $EPCListTestPointFilterParams.version = $Version }
                If ($Status) { $EPCListTestPointFilterParams.status = $Status; $EPCListTestPointFilterParams.statusSpecified = $TRUE }
                If ($RGName) { $RGID = (Get-EPCResourceGroup | Where-Object {$_.RGName -eq $RGName}).RGID }
                If ($RGID) { $EPCListTestPointFilterParams.RGList = $RGID }
                
                $EPCListTestPointParams.Filter = $EPCListTestPointFilterParams
            }
                        
            $TestPointResults = $Global:EPCWSDL_ActiveCtrl.listTestPoints($EPCListTestPointParams)
            Write-Verbose $TestPointResults.result

            If ($TestPointResults.result -eq 'success') {
                Return $TestPointResults.testptList
            }
            Else {
                Throw $TestPointResults.result
            }            
        }
        Else {
            Write-Verbose 'Using WebXML'
            $PwdEscaped = [System.Security.SecurityElement]::Escape($Global:EPControllerCred.GetNetworkCredential().Password)
            [xml]$SOAPReq = "<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
                xmlns:urn='urn:telchemyActiveCtrl'>
                 <soapenv:Header/>
                 <soapenv:Body>
                 <urn:listTestPointsParameters>
                <credentials>
                <username>$($Global:EPControllerCred.UserName)</username>
                <password>$PwdEscaped</password>
                </credentials>
                <maxNumber>$ResultSize</maxNumber>
                <includeHubResourceUsage>$($IncludeHubResourceUsage.ToString().ToLower())</includeHubResourceUsage>
                 </urn:listTestPointsParameters>
                 </soapenv:Body>
                </soapenv:Envelope>"

            # If any of the below parameters are specified, apply a filter
            If ($Name -Or $Status -Or $OrgID -Or $Version -Or $OSArch -Or $RGName -Or $RGID) {
                $FilterXMLElement = $SOAPReq.Envelope.Body.listTestPointsParameters.AppendChild($SOAPReq.CreateElement('filter'))
                
                If ($Name) { 
                    $NewXMLElement = $FilterXMLElement.AppendChild($SOAPReq.CreateElement('name-substring'))
                    $NULL = $NewXMLElement.AppendChild($SOAPReq.CreateTextNode($Name))
                }
                
                If ($Status) {
                    If ($Status -eq 'NotConnected') { $StatusFormatted = 'not connected' } Else { $StatusFormatted = $Status }
                    $NewXMLElement = $FilterXMLElement.AppendChild($SOAPReq.CreateElement('status'))
                    $NULL = $NewXMLElement.AppendChild($SOAPReq.CreateTextNode($StatusFormatted.ToLower()))                    
                }
                
                If ($OrgID) {
                    $NewXMLElement = $FilterXMLElement.AppendChild($SOAPReq.CreateElement('orgID'))
                    $NULL = $NewXMLElement.AppendChild($SOAPReq.CreateTextNode($OrgID.ToLower()))                    
                }

                If ($Version) {
                    $NewXMLElement = $FilterXMLElement.AppendChild($SOAPReq.CreateElement('version'))
                    $NULL = $NewXMLElement.AppendChild($SOAPReq.CreateTextNode($Version))                
                }
                
                If ($RGName) { 
                    $RGID = (Get-EPCResourceGroup | Where-Object {$_.RGName -eq $RGName}).RGID
                }
                
                If ($RGID) { 
                    $RGXMLElement = $FilterXMLElement.AppendChild($SOAPReq.CreateElement('RGList'))
                    $NewXMLElement = $RGXMLElement.AppendChild($SOAPReq.CreateElement('rg'))
                    $NULL = $NewXMLElement.AppendChild($SOAPReq.CreateTextNode($RGID))                
                }
            }

            $SOAPFQDN = "https://$Global:EPControllerFQDN/telchemywebservices/services/telchemyActiveCtrlService"
            Write-Verbose $SOAPFQDN
            Write-Verbose $SOAPReq.OuterXML

            If ($Global:EPC_UseSOAPHeader) {
                $Headers = @{'SOAPAction' = 'urn:telchemyActiveCtrl/listTestPointsParameters'}
            } Else {
                $Headers = @{}
            }
            
            [xml]$XMLResponse = (Invoke-WebRequest -UseBasicParsing -Method POST -URI $SOAPFQDN -Headers $Headers -Body $SOAPReq -ContentType 'text/xml').Content
            $TestPointResults = $XMLResponse.Envelope.Body.listTestPointsResults
            
            If ($TestPointResults.result -eq 'success') {
                Return $TestPointResults.testptList.testpt
            }
            Else {
                Throw $TestPointResults.result
            }
        }        
    }
}


Function Set-EPCTestPoint {
    <#
        .SYNOPSIS
        Update the name and/or description for a given EPC test point
         
        .DESCRIPTION
        Update the name and/or description for a given EPC test point
         
        .PARAMETER UUID
        The UUID of the test point to update
         
        .PARAMETER Name
        The display name to set on the test point
         
        .PARAMETER Description
        The description to set on the test point
 
        .EXAMPLE
        Set-EPCTestPoint -UUID d4a1437f-1f18-11ec-cf33-0daedf04882a -Name 'New Name' -Description 'Updated description'
        Updates the selected test point's name and description
 
        .NOTES
        Version 1.0
    #>
    
    [cmdletbinding()]
    Param (
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$True)]
        [Alias("ID")]
        [string]$UUID,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [Alias("UserDisplayName")]
        [string]$DisplayName,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [string]$Description    
    )
    
    Begin {
        Get-EPCWebSessionCookie
        $ProgressPreference = 'SilentlyContinue'
    }
    Process {
        $TPFQDN = "https://$EPControllerFQDN/test/testPoint.do?action=2"
        
        # If name isn't set, pull the name from the existing record, otherwise it will replace the name with its IP address
        If (!$DisplayName) { $DisplayName = (Get-EPCTestPoint -UUID $UUID).Name }
        
        $TPBody = @{
            tptype = 1
            uuid = $UUID
            name = $DisplayName
        }
        
        If ($Description) { $TPBody.Add('description',$Description -Replace "[^\sa-zA-Z0-9.-]") }

        Write-Verbose "UUID: $UUID, Name: $DisplayName"
        
        $NULL = Invoke-WebRequest -UseBasicParsing -Method POST -Uri $TPFQDN -Body $TPBody -WebSession $Global:EPCSessionCookie
    }
}


Function Get-EPCTestPointInterface {
    <#
        .SYNOPSIS
        Return network interface inforemation for a given EPC test point
         
        .DESCRIPTION
        Return network interface inforemation for a given EPC test point
         
        .PARAMETER ID
        The ID of the test point to retrieve information about
         
        .EXAMPLE
        Get-EPCTestPointInterface -ID d4a1437f-1f18-11ec-cf33-0daedf04882a
        Returns network interface information about a specific test point
 
        .NOTES
        Version 1.0
    #>

    [cmdletbinding()]
    Param (
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$True)]
        [Alias('testptID', 'EndpointID')]
        [string]$UUID,
        [switch]$UseXML
    )
    
    Begin {
        Connect-EPCController
        
        If ($Global:EPC_UseWSDL -And $UseXML -eq $False) {
            $EPCCred = New-Object -TypeName EPC.ActiveCtrl.CredentialsType
            $EPCCred.username = $Global:EPControllerCred.UserName
            $EPCCred.password = $Global:EPControllerCred.GetNetworkCredential().Password
        }
        Else {
            $ProgressPreference = 'SilentlyContinue'
        }
    }
    Process {
        If ($Global:EPC_UseWSDL -And $UseXML -eq $False) {
            Write-Verbose 'Using WSDL to pull interface list'
            $EPCListTestPointInterfaceParams = New-Object -TypeName EPC.ActiveCtrl.ListTestPointInterfaceParametersType
            $EPCListTestPointInterfaceParams.credentials = $EPCCred
            $EPCListTestPointInterfaceParams.testptID = $UUID
            $TestPointInterfaceResults = $Global:EPCWSDL_ActiveCtrl.listTestPointInterfaces($EPCListTestPointInterfaceParams)
            Write-Verbose $TestPointInterfaceResults.result
            
            If ($TestPointInterfaceResults.result -eq 'success') {
                Return $TestPointInterfaceResults.InterfaceList
            }
            Else {
                Throw $TestPointInterfaceResults.result
            }
        }
        Else {
            Write-Verbose 'Using XML to pull interface list'
            $PwdEscaped = [System.Security.SecurityElement]::Escape($Global:EPControllerCred.GetNetworkCredential().Password)
            [xml]$SOAPReq = "<soapenv:Envelope xmlns:soapenv='http://schemas.xmlsoap.org/soap/envelope/'
                xmlns:urn='urn:telchemyActiveCtrl'>
                 <soapenv:Header/>
                 <soapenv:Body>
                 <urn:listTestPointInterfaceParameters>
                <credentials>
                <username>$($Global:EPControllerCred.UserName)</username>
                <password>$PwdEscaped</password>
                </credentials>
                <testptID>$UUID</testptID>
                 </urn:listTestPointInterfaceParameters>
                 </soapenv:Body>
                </soapenv:Envelope>"
                
            $SOAPFQDN = "https://$Global:EPControllerFQDN/telchemywebservices/services/telchemyActiveCtrlService"
            Write-Verbose $SOAPFQDN
            Write-Verbose $SOAPReq.OuterXML

            If ($Global:EPC_UseSOAPHeader) {
                $Headers = @{'SOAPAction' = 'urn:telchemyActiveCtrl/listTestPointInterfaceParameters'}
            } Else {
                $Headers = @{}
            }
            
            [xml]$XMLResponse = (Invoke-WebRequest -UseBasicParsing -Method POST -URI $SOAPFQDN -Headers $Headers -Body $SOAPReq -ContentType 'text/xml').Content
            $TestPointInterfaceResults = $XMLResponse.Envelope.Body.listTestPointInterfaceResults
            
            If ($TestPointInterfaceResults.result -eq 'success') {
                [psobject]$TestPointInterfaces = $TestPointInterfaceResults.InterfaceList.interface | ConvertFrom-XMLElement
                Return $TestPointInterfaces
            }
            Else {
                Throw $TestPointInterfaceResults.result
            }
        }
    }
}


Function Get-EPCTestPointEvent {
    <#
        .SYNOPSIS
        Returns a list of EPC test groups and their associated IDs
         
        .DESCRIPTION
        Returns a list of EPC test groups and their associated IDs
 
        .PARAMETER ResultSize
        The number of results to return. Defaults to 1000.
         
        .EXAMPLE
        Get-EPCTestPointEvent
 
        .NOTES
        Version 1.0
    #>
    
    [cmdletbinding()]
    Param (
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [Alias("testptID")]
        [string]$TestPointID,
        [Parameter(ValueFromPipelineByPropertyName, Mandatory=$False)]
        [string]$TestPointName,
        [Parameter(Mandatory=$False)]
        [ValidateSet('LAST_HOUR','LAST_DAY','LAST_WEEK','LAST_MONTH','ALL','CUSTOM', IgnoreCase=$True)]
        [string]$TimePeriod = 'LAST_DAY',
        [Parameter(Mandatory=$False)]
        [Alias("StartDateFrom")]
        [datetimeoffset]$TimePeriodFrom,
        [Parameter(Mandatory=$False)]
        [Alias("StartDateTo")]
        [datetimeoffset]$TimePeriodTo,        
        [Parameter(Mandatory=$False)]
        [ValidateSet('Any','Fatal','Error','Warn','Info','Debug', IgnoreCase=$True)]
        [string]$EventLevel = 'Any',
        [Parameter(Mandatory=$False)]
        [ValidateSet('Any','Reporter','Controller','Agent', IgnoreCase=$True)]
        [string]$AppType = 'Any',        
        [Parameter(Mandatory=$False)]
        [string]$SortColumn = 'evt_date',        
        [Parameter(Mandatory=$False)]
        [int]$ResultSize = 1000
    )
    
    Begin {
        Get-EPCWebSessionCookie
        $ProgressPreference = 'SilentlyContinue'
    }
    Process {
        $Body = @{
            action = 3
            filter = $EventLevel.ToLower()
        }
        
        If ($AppType -ne 'Any') {
            Switch ($AppType) {
                'Reporter' { $AppTypeID = 2 }
                'Controller' { $AppTypeID = 3 }
                'Agent' { $AppTypeID = 4 }
            }
            $Body.Add('apptype', $AppTypeID)
        }
        
        If ($TimePeriod -ne 'ALL') {
            Switch ($TimePeriod) {
                'LAST_HOUR' { $TimePeriodFrom = [DateTimeOffset]::Now.AddHours(-1); $TimePeriodTo = [DateTimeOffset]::Now }
                'LAST_DAY' { $TimePeriodFrom = [DateTimeOffset]::Now.AddDays(-1); $TimePeriodTo = [DateTimeOffset]::Now }
                'LAST_WEEK' { $TimePeriodFrom = [DateTimeOffset]::Now.AddDays(-7); $TimePeriodTo = [DateTimeOffset]::Now }
                'LAST_MONTH' { $TimePeriodFrom = [DateTimeOffset]::Now.AddMonths(-1); $TimePeriodTo = [DateTimeOffset]::Now }
            }
            
            If (!$TimePeriodTo) { $TimePeriodTo = [DateTimeOffset]::Now }
            
            $Body.Add('beginsecs', $TimePeriodFrom.ToUnixTimeSeconds())
            $Body.Add('endsecs', $TimePeriodTo.ToUnixTimeSeconds())
        }
        
        If ($TestPointID) { $Body.Add('hostuuid', $TestPointID) }
        
        If ($TestPointName) { 
            $TestPointID = (Get-EPCTestPoint -Name $TestPointName -ResultSize 1).testptID
            
            If (!$TestPointID) { Throw "Could not find test point with name $TestPointName" }

            $Body.Add('hostuuid', $TestPointID)
        }
        
        $TPEFQDN = "https://$Global:EPControllerFQDN/admin/eventLogs.do"
        $TPEResult = Invoke-RestMethod -Method GET -Uri $TPEFQDN -WebSession $Global:EPCSessionCookie -Body $Body

        $FormattedResults = $TPEResult.events | Select-Object application, host, appCode, @{Name='time';Expression={(([System.DateTimeOffset]::FromUnixTimeMilliSeconds($_.Time)).LocalDateTime).ToString("yyyy-MM-dd HH:mm:ss.fff")}}, priority, message
        Return $FormattedResults
    }
}