- AutomationTools
A set of tools for general automation purposes
A collection of commonly used functions for automation tasks, as well as automatic handling of some commonly used items, including script and module config. These items are collected in order to help reduce the amount of repeat code written when writing new automation tasks.
By default, autmoationtools will ingest the config file included with the module. It will also search for a config file accompanying the current calling script and update the internal config with one or both of these files. The files will be overwritten in the order that they are added.
Config files are intended to be simple JSON structures that maintain a list of variables used by the currently running function. The focus behind the config file is to avoid having individuals or automations opening or editing files manually. Scripts can more easily be deployed with custom settings simply by including an accompanying config.json file.
AutomationTools can detect and ingest multiple config.json files. These files follow an order of importance where the file last to be consumed will contain the new current config value. By default, AutomationTools loads config.json located inside the module root, then config.json inside the calling script root directory, then any subsequent manually added files.
First Load
config.json inside module root
-Module Root
--ModuleFolder
--AutomationTools.psm1
--AutomationTools.psd1
--config.json
Second Load
config.json inside calling script root
-Script Root
--Script.ps1
--config.json
Normal JSON structure
{
"ConfigVariableName":"ConfigVariableValue",
}While these are intended to be simple structures, automationtools will ingest and assign more complicated structures. That said, if a complicated structure is required than it is most likely outside of the scope of config.
There are several defaults that automationtools uses that can be easily overwritten in the default config. These include:
ModuleRoot- The root location of the moduleLogRoot- The root location of the logging locationLogName- The name of the log fileMaxLogCount- The maximum amount of logs retained in memory, defaulted to 30,000EventSource- The name of the Windows Event Source nameSMTPServer- The server address for SMTP messagesSMTPFrom- The sending address for SMTP messaagesSMTPPort- The port to be used with the SMTP serverSMTPUseSSL- The flag to indicate if SMTP should be using SSLTemplatesRoot- The root location for HTML templatesDefaultJobReportTemplate- The location of the default Send-JobReport templateHTMLHelpers- Helpers for replacing content inside HTML templatsDefaultToLog- Indicator of whether or not all non-SYS/VRB messages should be sent to log fileDefaultToConsole- Indicator of whether or not all non-SYS/VRB messages should be sent to consoleDefaultToEvent- Indicator of whether or not all non-SYS/VRB messages should be sent to the Windows Event LogDefaultEventID- The default Event ID to be given to the Windows Event Log should one not be included in the messageDefaultSYSConsole- Indicator of whether or not all SYS messages should be sent to the consoleDefaultSYSLog- Indicator of whether or not all SYS messages should be sent to logDefaultSYSEvent- Indicator of whether or not all SYS messages should be sent to the Windows Event LogDefaultVRBConsole- Indicator of whether or not all VRB messages should be sent to the consoleDefaultVRBLog- Indicator of whether or not all VRB messages should be sent to logDefaultVRBEvent- Indicator of whether or not all VRB messages should be sent to the Windows Event LogMinimumPSVersion- The minimum PS version that tools will supportRunLocation- The location of the calling entity, this value will be eitherSCRIPTorCONSOLERunFile- The name of the script currently calling, this defaults to blank ifRunLocationis blankInvokeRoot- The root of the script currently calling automationtoolsInvokeSecrets- The location of the current secrets.json file used for Add-Secret,Get-Secret, and Remove-Secret
Module root config loading happens automatically at time of import. Script-level config load happens simply by calling the module's Get-Config function. Additional config files should be loaded prior to calling Get-Config by calling the Add-ToolConfig function.
If you're adding a third or additional config file:
Add-ToolConfig -Path "C:\Path\To\New\config.json"
$Config = Get-ConfigFor normal operation use:
$Config = Get-ConfigAny changes to the config after this point will require Get-Config be called again as this is a snapshot of the living config inside AutomationTools.
Write-Log is a single-point of communication between an automation and various external publishing sources. It is intended to unify output across various locations for quick diagnosis, error capture, and reporting. This maintained log is defaulted to 30,000 logs before being rewritten.
The standard output for log information reads as follows
Standard Log
Write-Log -Message "Example Message" -Type INF -ConsoleOutputs
INF | 07/22/20 18:07:26 | Example Message
This contains a log level, a datetime stamp, and the included message. There are several scenarios where the message will be further formatted to include unique data, one of which is error capture.
Error capture
$_ | Write-Log -Message "Could not find [$FileName]" -Type ERR -ConsoleOutputs
ERR | 07/22/20 13:46:02 | Could not find [File.txt]. Exception [File not found] was thrown in [C:\Script.ps1] at line [$Content = Get-Content $FileName], line number [35], position [8].
Additional routing and formatting can occur based off of log level, so it is important to use proper log levels
INF- Information, maps to Information inside Event LogWRN- Warning, maps to Warning inside Event LogERR- Error, maps to Error inside Event LogHDR- Header, maps to Information inside Event Log and is used to mark new jobsCON- Connection, maps to SuccessAudit inside Event LogDIS- Disconnection, maps to SuccessAudit inside Event LogRES- Result, maps to Information inside Event Log, used to automatically determine job resultsSYS- System, maps to Information inside Event Log. This is intended for hidden Module-Level loggingVRB- Verbose, maps to Information inside Event Log. This is intended to use and display with the -Verbose flag on advanced functions
Both SYS and VRB are hidden from console view by default as they are intended to be used for Verbose logging and/or debugging
Config Controls
DefaultToConsole
DefaultSYSConsole
DefaultVRBConsole
Write-Log -Message "Example Message" -Type INF -ConsoleOutputs directly to PowerShell console, if available
Config Controls
LogRoot
LogName
DefaultToLog
DefaultSYSLog
DefaultVRBLog
Write-Log -Message "Example Message" -Type INF -LogOutputs directly to Log file located in $Config.LogRoot
Write-Log -Message "Example Message" -Type INF -Log -SecondaryLog $PathOutputs directly to Log file located in $Config.LogRoot as well as a log file located in $Path
Write-Log -Message "Example Message" -Type INF -Log -Path $PathOutputs directly to Log file located in $Path
Config Controls
EventSource
DefaultEventID
DefaultVRBEvent
DefaultToEvent
DefaultSYSEvent
DefaultVRBEvent
Write-Log -Message "Example Message" -Type INF -EventLogOutputs directly to Event Log with source in $Config.EventSource with Event ID $Config.DefaultEventID
Write-Log -Message "Example Message" -Type INF -EventLog -Source "NewSource" -EventID 9001Outputs directly to Event Log with source NewSource and Event ID 9001
NOTE: You must have elevated privileges to create a new source in the Event Log
Write-Log -Message "Example Message" -Type INF -Log -Path $PathOutputs directly to Log file located in $Path
Config Controls
SMTPServer
SMTPFrom
SMTPPort
SMTPUseSSL
DefaultJobReportTemplate
Sending email reports is sometimes a necessary evil. Some base-level convenience tools have been added into AutomationTools in order to speed up the repetitive processes. These tools now include auto-table highlighting, table injection, and formatting.
Send-JobReport -To "[email protected]" -Subject "This is a test report" -Pretty
Row highlighting is automatically included when using the -Pretty switch. Behind the scenes this uses the Row and Cell match flags from the table conversion and templating section below.
Convert-ArrayListToHTML Details
Add-TablesToHTMLJobTemplate Details
$Tables = New-Object System.Collections.Generic.List[PSCustomObject]
$Table1 = Convert-ArrayListToHTMLTable -List $TestData1 -TableName "Foods" -WarnRowMatch "1|3" -FailRowMatch "3" -FailCellMatch "Cookies 6" -Limit 10
$Table2 = Convert-ArrayListToHTMLTable -List $TestData2 -TableName "Animals" -SuccessCellMatch "Snake|Hippo 3|Elephant 1" -WarnCellMatch "Hippo 1" -Limit 10
$Tables.Add($Table1)
$Tables.Add($Table2)
$Template = Add-TablesToHTMLJobTemplate -TableList $Tables -Description "This is a description of the email as a whole"
Send-HTMLEmail -HTMLData ($Template | Out-String) -Subject "Testing" -To "[email protected]"
Convert-ArrayListToHTMLTable now supports conditional formatting with regex row and cell matching via the following commands
FailRowMatch- Scans the row for regex match and fails the entire row based on match conditionsSuccessRowMatch- Scans the row for regex match and succeeds the entire row based on match conditionsWarnRowMatch- Scans the row for regex match and warns the entire row based on match conditionsFailCellMatch- Scans each cell for regex match and fails the individual cell based on match conditionsSuccessCellMatch- Scans each cell for regex match and succeeds the individual cell based on match conditionsWarnCellMatch- Scans each cell for regex match and warns the individual cell based on match conditions
Config Controls
InvokeSecrets
For general script testing purposes credentials are often required. AutomationTools will assist in storage, retrevial, and removal of credential combinations. For now this is a simple JSON file with username/secure string pairs, but it will eventually be moved into the Winows Credentials Store. There are security concerns with both solutions, so this is by no means intended for production purposes. It is only intended for use in organizing commonly used credential sets while testing and debugging
NOTE: It is important to add an ignore rule for secrets.json inside gitignore
$Credential = Get-Credential
Add-Secret -Name "CredentialSetName" -Credential $CredentialThis will create a username/secure string pair in the root of the calling script or console named secrets.json. These credentials can only be used on the origin box by the origin user.
$Credentials = Get-Secret -Name "CredentialSetName"This will get a username/secure string pair in the root of the calling script or console named secrets.json. These credentials can only be retrieved on the origin box by the origin user.
Remove-Secret -Name "CredentialSetName"This will remove the username/secure string pair from the secrets.json file.
AutomationTools has a few file management tools used to remove the thought process behind nested folders not existing. These tools are simple but reduce some repeat code.
Resolve-Folder -Path "C:\Test\Folder\Location"Tests if the folder structure exists, and creates it if it does not. This is recursive
Resolve-File -Path "C:\Test\Folder\Location\testFile.txt"Tests if the file exists, and creates it if it does not. This is recursive
Test-FolderWrite -Path "C:\TestFolder"Tests if the current user has write permission to the specified folder. The test does not create a file, but opens and closes a file stream
A few common conversion tools for use in general scripts
"1.0.0.1" | ConvertTo-VersionOutputs a Version object, useful for quickly comparing different versions levels of various softwares or files
$Hash | Convert-HashToPSObjectOutputs a PSObject given a standard hash. It will preserve nesting
$Array = @(
"netstat",
"-ano"
)
$Array | Convert-ArrayToScriptBlockOutputs a ScriptBlock given a standard array. This is useful in mocking Invoke-Command calls dynamically
A small collection of general purpose utilities
[PSObject]$Template
$NewObj = $Template | Copy-PSObjectReturns a copy of the given PSObject. Generally assigning a PSObject to two variables creates a reference and not a new object
Test-ElevationReturns a bool of the current user's administration status. The principal to check can be overwritten with -RoleOverride
Add-ToolConfig -Path "C:\Path\To\New\Config.json"Adds contents of the json file into AutomationTools config
Update-Config -Name "TestAdd" -Value "TestValue"Adds an ad-hawk config element to the AutomationTools config variable
Invoke-ScheduledTask -TaskName "Test" -ComputerName "TargetComputer"Invokes a scheduled task on a remote machine via CIM session. Has an optional paramter -Wait that will wait for the Scheduled Task to finish. This is an older function and will be upgraded in the future