Public/Get-AtwsInvoiceInfo.ps1
|
#Requires -Version 4.0 <# .COPYRIGHT Copyright (c) Office Center Hønefoss AS. All rights reserved. Licensed under the MIT license. See https://github.com/officecenter/Autotask/blob/master/LICENSE.md for license information. #> Function Get-AtwsInvoiceInfo { <# .SYNOPSIS This function collects information about a specific Autotask invoice object and returns a generic powershell object with all relevant information as a starting point for import into other systems. .DESCRIPTION The function accepts an invoice object or an invoice id and makes a special API call to get a complete invoice description, including billingitems. For some types of billingitems additional information may be collected. All information is collected and stored in a PSObject which is returned. .INPUTS An Autotask invoice object or an invoice id .OUTPUTS A custom PSObject with detailed information about an invoice .EXAMPLE $Invoice | Get-#PrefixInvoiceInfo Gets information about invoices passed through the pipeline .EXAMPLE Get-#PrefixInvoiceInfo -InvoiceID $Invoice.id Gets information about invoices based on the ids passed as a parameter .NOTES NAME: Get-#PrefixInvoiceInfo #> [cmdletbinding()] Param ( [Parameter( Mandatory = $true, ValueFromPipeLine = $true, ParameterSetName = 'Input_Object' )] [Autotask.Invoice[]] $InputObject, [Parameter( Mandatory = $true, ParameterSetName = 'By_parameters' )] [string[]] $InvoiceId, [switch] $XML ) begin { # Enable modern -Debug behavior if ($PSCmdlet.MyInvocation.BoundParameters['Debug'].IsPresent) { $DebugPreference = 'Continue' } if (-not($Script:Atws.Url)) { Throw [ApplicationException] 'Not connected to Autotask WebAPI. Re-import module with valid credentials.' } # Input was by object. Extract invoice ids into an array and proceed if ($PSCmdlet.ParameterSetName -eq 'Input_Object') { $InvoiceId = $InputObject.id } } process { # Empty container to return with results $result = @() # Get detailed invoice info through special API call. Have to call # API once for each invoice. Second parameter says we want the result # as XML. Actually we don't, but the alternative (HTML) is worse. Write-Verbose ('{0}: Asking for details on Invoice IDs {1}' -F $MyInvocation.MyCommand.Name, ($InvoiceId -join ', ')) ForEach ($id in $InvoiceId) { # The API call. Make sure to query the correct WebServiceProxy object # specified by the $Prefix name. If the Id does not exist we get a # SOAP exception for some inexplicable reason try { [Xml]$invoiceInfo = $Script:Atws.GetInvoiceMarkup($id, 'XML') } catch { Write-Warning ('{0}: FAILED on Invoice ID {1}. No data returned.' -F $MyInvocation.MyCommand.Name, $id) # try the next ID Continue } Write-Verbose ('{0}: Converting Invoice ID {1} to a PSObject' -F $MyInvocation.MyCommand.Name, $id) if ($XML.IsPresent) { $result += $invoiceInfo.invoice_batch_generic } else { $result += $invoiceInfo.invoice_batch_generic | ConvertFrom-XML } } } end { return $result } } |