Autotask.psm1
|
<#
.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. #> [CmdletBinding()] Param( [Parameter( Position = 0 )] [pscredential] $Credential = $Global:AtwsCredential, [Parameter( Position = 1 )] [String] $ApiTrackingIdentifier = $Global:AtwsApiTrackingIdentifier, [Parameter( Position = 2, ValueFromRemainingArguments = $True )] [String[]] $EntityName = $Global:AtwsRefreshCachePattern ) Write-Debug ('{0}: Start of module import' -F $MyInvocation.MyCommand.Name) # Special consideration for -Verbose, as there is no $PSCmdLet context to check if Import-Module was called using -Verbose # and $VerbosePreference is not inherited from Import-Module for some reason. # Remove comments $ParentCommand = ($MyInvocation.Line -split '#')[0] # Store Previous preference $OldVerbosePreference = $VerbosePreference If ($ParentCommand -like '*-Verbose*') { Write-Debug ('{0}: Verbose preference detected. Verbose messages ON.' -F $MyInvocation.MyCommand.Name) $VerbosePreference = 'Continue' } $OldDebugPreference = $DebugPreference If ($ParentCommand -like '*-Debug*') { Write-Debug ('{0}: Debug preference detected. Debug messages ON.' -F $MyInvocation.MyCommand.Name) $DebugPreference = 'Continue' } # Am I being loaded as the Beta version? If ($MyInvocation.MyCommand.Name -eq 'AutotaskBeta.psm1') { $Script:IsBeta = $True } # Read our own manifest to access configuration data $ManifestFileName = $MyInvocation.MyCommand.Name -replace 'pdm1$', 'psd1' $ManifestDirectory = Split-Path $MyInvocation.MyCommand.Path -Parent Write-Debug ('{0}: Loading Manifest file {1} from {2}' -F $MyInvocation.MyCommand.Name, $ManifestFileName, $ManifestDirectory) Import-LocalizedData -BindingVariable My -FileName $ManifestFileName -BaseDirectory $ManifestDirectory # Get all function files as file objects # Private functions can only be called internally in other functions in the module $PrivateFunction = @( Get-ChildItem -Path $PSScriptRoot\Private\*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Found {1} script files in {2}\Private' -F $MyInvocation.MyCommand.Name, $PrivateFunction.Count, $PSScriptRoot) # Public functions will be exported with Prefix prepended to the Noun of the function name $PublicFunction = @( Get-ChildItem -Path $PSScriptRoot\Public\*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Found {1} script files in {2}\Public' -F $MyInvocation.MyCommand.Name, $PublicFunction.Count, $PSScriptRoot) # Static functions will be exported with Prefix prepended to the Noun of the function name $StaticFunction = @( Get-ChildItem -Path $PSScriptRoot\Static\*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Found {1} script files in {2}\Static' -F $MyInvocation.MyCommand.Name, $StaticFunction.Count, $PSScriptRoot) # Static functions will be exported with Prefix prepended to the Noun of the function name $DynamicFunction = @( Get-ChildItem -Path $PSScriptRoot\Dynamic\*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Found {1} script files in {2}\Dynamic' -F $MyInvocation.MyCommand.Name, $DynamicFunction.Count, $PSScriptRoot) Write-Verbose ('{0}: Importing {1} Private and {2} Public functions.' -F $MyInvocation.MyCommand.Name, $PrivateFunction.Count, $PublicFunction.Count) # Loop through all script files and source them foreach ($Import in @($PrivateFunction + $PublicFunction)) { Write-Debug ('{0}: Importing {1}' -F $MyInvocation.MyCommand.Name, $Import) try { . $Import.fullname } catch { throw "Could not import function $($Import.fullname): $_" } } # If they tried to pass any variables If (($Credential) -or ($ApiTrackingIdentifier)) { Write-Verbose ('{0}: Credentials detected. Connecting to Autotask API' -F $MyInvocation.MyCommand.Name) # Remove Global variables (if used) for security $MyGlobalVars = Get-Variable -Scope Global -ErrorAction SilentlyContinue $TargetVarNames = 'AtwsCredential', 'AtwsApiTrackingIdentifier', 'AtwsRefreshCachePattern', 'AtwsUsePicklistLabels', 'AtwsNoDiskCache' $ConnectArgs = @{ Credential = $Credential ApiTrackingIdentifier = $ApiTrackingIdentifier } switch ($MyGlobalVars | Where-Object { $_.Name -in $TargetVarNames }) { { $_.Name -eq 'AtwsCredential' } { Write-Debug ('{0}: Credentials for {1} detected.' -F $MyInvocation.MyCommand.Name, $AtwsCredential.UserName) # Remove Global Object, credentials are now stored in a variable internal to the module Remove-Variable -Name $_.Name -Scope Global continue } { $_.Name -eq 'AtwsApiTrackingIdentifier' } { Write-Debug ('{0}: API tracking identifier for {1} detected.' -F $MyInvocation.MyCommand.Name, $AtwsCredential.UserName) # Remove Global Object, credentials are now stored in a variable internal to the module Remove-Variable -Name AtwsApiTrackingIdentifier -Scope Global continue } { $_.Name -eq 'AtwsRefreshCachePattern' } { Write-Debug ('{0}: Refreshing disk cache by force' -F $MyInvocation.MyCommand.Name) # Remove Global Object Remove-Variable -Name AtwsRefreshCachePattern -Scope Global continue } { $_.Name -eq 'AtwsUsePicklistLabels' } { Write-Debug ('{0}: Converting picklistvalues to their labels are turned ON' -F $MyInvocation.MyCommand.Name) $Script:UsePickListLabels = $True # Remove Global Object Remove-Variable -Name AtwsUsePicklistLabels -Scope Global continue } { $_.Name -eq 'AtwsNoDiskCache' } { Write-Debug ('{0}: Force No disk cache detected. All functions are loaded from the scripts supplied by the module.' -F $MyInvocation.MyCommand.Name) Write-Verbose ('{0}: Force No disk cache detected. All functions are loaded from the scripts supplied by the module.' -F $MyInvocation.MyCommand.Name) # Remove Global Object, credentials are now stored in a variable internal to the module Remove-Variable -Name AtwsNoDiskCache -Scope Global # Add the NoDiskCache switch to the splatted arguments we will use to connect $ConnectArgs['NoDiskCache'] = $true } default { } } # Connect to the API using required, additional parameters, using internal function name . Connect-AtwsWebServices @ConnectArgs if (!$ConnectArgs['NoDiskCache']) { If ($IsBeta) { $DynamicCache = '{0}\WindowsPowershell\Cache\{1}\Beta' -f $([environment]::GetFolderPath('MyDocuments')), $Script:Atws.CI } Else { $DynamicCache = '{0}\WindowsPowershell\Cache\{1}\Dynamic' -f $([environment]::GetFolderPath('MyDocuments')), $Script:Atws.CI } If (Test-Path $DynamicCache) { $FunctionCount = $DynamicFunction.Count $DynamicFunction = @( Get-ChildItem -Path $DynamicCache\*atws*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Personal disk cache: Found {1} script files in {2}' -F $MyInvocation.MyCommand.Name, $DynamicFunction.Count, $DynamicCache) $VersionString = "#Version {0}" -F $My.ModuleVersion $ScriptVersion = Select-String -Pattern $VersionString -Path $DynamicFunction.FullName If ($ScriptVersion.Count -ne $FunctionCount) { Write-Debug ('{0}: Personal disk cache: Wrong number of script files or scripts are not the right version in {1}, refreshing all entities.' -F $MyInvocation.MyCommand.Name, $DynamicCache) # Clear out old cache, it will be recreated $Null = Remove-Item -Path $DynamicFunction.fullname -Force -ErrorAction SilentlyContinue # Refresh ALL dynamic entities. $EntityName = '*' } $OldFunctions = @(Get-ChildItem -Path $DynamicCache\*.ps1 -Exclude *Atws* -ErrorAction SilentlyContinue) If ($OldFunctions.Count -gt 0) { Write-Debug ('{0}: Personal disk cache: Found {1} old script files in {2}. Deleting.' -F $MyInvocation.MyCommand.Name, $OldFunctions.Count, $DynamicCache) $Null = Remove-Item -Path $OldFunctions.fullname -Force -ErrorAction SilentlyContinue } } Else { Write-Debug ('{0}: Personal disk cache {1} does not exist. Forcing load of all dynamic entities.' -F $MyInvocation.MyCommand.Name, $DynamicCache) # No personal dynamic cache. Refresh ALL dynamic entities. $EntityName = '*' } # Refresh any entities the caller has ordered # We only consider entities that are dynamic $Entities = Get-AtwsFieldInfo -Dynamic $EntitiesToProcess = @() Write-Debug ('{0}: {1} dynamic entities are eligible for refresh.' -F $MyInvocation.MyCommand.Name, $DynamicCache) Foreach ($String in $EntityName) { Write-Debug ('{0}: Selecting entities that match pattern "{1}"' -F $MyInvocation.MyCommand.Name, $String) $EntitiesToProcess += $Entities.GetEnumerator().Where( { $_.Key -like $String }) } # Prepare Index for progressbar $Index = 0 $ProgressParameters = @{ Activity = 'Updating diskcache for requested entities.' Id = 10 } # Make sure we only check each possible entity once $EntitiesToProcess = $EntitiesToProcess | Sort-Object -Property Name -Unique Write-Debug ('{0}: {1} entities have been selected for refresh' -F $MyInvocation.MyCommand.Name, $EntitiesToProcess.Count) Foreach ($EntityToProcess in $EntitiesToProcess) { $Index++ $PercentComplete = $Index / $EntitiesToProcess.Count * 100 # Add parameters for @splatting $ProgressParameters['PercentComplete'] = $PercentComplete $ProgressParameters['Status'] = 'Entity {0}/{1} ({2:n0}%)' -F $Index, $EntitiesToProcess.Count, $PercentComplete $ProgressParameters['CurrentOperation'] = 'Getting fieldinfo for {0}' -F $EntityToProcess.Name Write-Progress @ProgressParameters $null = Get-AtwsFieldInfo -Entity $EntityToProcess.Key -UpdateCache } If ($EntitiesToProcess.Count -gt 0) { Write-Debug ('{0}: Calling Import-AtwsCmdLet with {1} entities to process' -F $MyInvocation.MyCommand.Name, $EntitiesToProcess.Count) # Recreate functions that have been updated Import-AtwsCmdLet -Entities $EntitiesToProcess # Re-read Dynamic functions $DynamicFunction = @( Get-ChildItem -Path $DynamicCache\*atws*.ps1 -ErrorAction SilentlyContinue ) Write-Debug ('{0}: Personal disk cache: Found {1} script files in {2}' -F $MyInvocation.MyCommand.Name, $DynamicFunction.Count, $DynamicCache) } } Write-Verbose ('{0}: Importing {1} Static and {2} Dynamic functions.' -F $MyInvocation.MyCommand.Name, $StaticFunction.Count, $DynamicFunction.Count) # Loop through all script files and source them foreach ($Import in @($StaticFunction + $DynamicFunction)) { Write-Debug ('{0}: Importing {1}' -F $MyInvocation.MyCommand.Name, $Import) try { . $Import.fullname } catch { throw "Could not import function $($Import.fullname): $_" } } # Explicitly export public functions Write-Debug ('{0}: Exporting {1} Public functions.' -F $MyInvocation.MyCommand.Name, $PublicFunction.Count) Export-ModuleMember -Function $PublicFunction.Basename # Explicitly export static functions Write-Debug ('{0}: Exporting {1} Static functions.' -F $MyInvocation.MyCommand.Name, $StaticFunction.Count) Export-ModuleMember -Function $StaticFunction.Basename # Explicitly export dynamic functions Write-Debug ('{0}: Exporting {1} Dynamic functions.' -F $MyInvocation.MyCommand.Name, $DynamicFunction.Count) Export-ModuleMember -Function $DynamicFunction.Basename } Else { Write-Verbose 'No Credentials were passed with -ArgumentList. Loading module without any connection to Autotask Web Services. Use Connect-AtwsWebAPI to connect.' Export-ModuleMember -Function 'Connect-AtwsWebAPI' } # Backwards compatibility since we are now trying to use consistent naming Set-Alias -Scope Global -Name 'Connect-AutotaskWebAPI' -Value 'Connect-AtwsWebAPI' # Restore Previous preference If ($OldVerbosePreference -ne $VerbosePreference) { Write-Debug ('{0}: Restoring old Verbose preference' -F $MyInvocation.MyCommand.Name) $VerbosePreference = $OldVerbosePreference } If ($OldDebugPreference -ne $DebugPreference) { Write-Debug ('{0}: Restoring old Debug preference' -F $MyInvocation.MyCommand.Name) $DebugPreference = $OldDebugPreference } |