ReadMe

Content

Basics
Disclaimer and Warning
Release Notes
[How to connect][8]
[How to connect on Azure][12]
[How to Get data from the API][4]
[How to create New entities through the API][5]
[How to Update (make changes) to entities][6]
[How to Remove entities][7]
[Best Practices][9]
[Null values][10]
[User Defined Fields][11]

Basics

Install the module from PowerShell Gallery (the published module version is based on branch "master". Any prerelease version is based on a snapshot of "Development"):

# Download and install the module
Install-Module Autotask

# Connect to the Autotask Web Services API
$Credential = Get-Credential # Your Autotask API user and password
$ApiKey = "<the API identifier from your resource in Autotask>"
Connect-AtwsWebAPI -Credential $Credential -ApiTrackingIdentifier $ApiKey

# Save your credentials locally (NB! Will be exported as SecureString in CliXML)
New-AtwsModuleConfiguration -Credential $Credential -SecureTrackingIdentifier ($ApiKey | ConvertTo-SecureString -AsPlainText -Force) -ProfileName Default

# Module can now load and connect automatically, so you can run any command directly
Get-AtwsAccount -id 0

# New options, can be changed at runtime with Set-AtwsModuleConfiguration
New-AtwsModuleConfiguration -PickListExpansion <String> (Disabled|Inline|Labelfield)
New-AtwsModuleConfiguration -UdfExpansion <String>      (Disabled|Inline|Hashtable)
New-AtwsModuleConfiguration -DateConversion <String>    (Disabled|Local|specific/timezone)

Get-Help New-AtwsModuleConfiguration

Disclaimer and Warning

Be careful! This module exposes all the Autotask Web Services API entities and methods as PowerShell functions. This makes it very easy to make a lot of changes very quickly. But there is no undo! If you use this module to destroy or delete anything in your Autotask tenant you did not intend to - you are entirely on your own! This module is provided "as is", without warranty of any kind, express or implied. In no event shall the authors or copyright holders be liable for any claim, damages or other liability ([see the license][3]). If this is not acceptable to you - do not use it!

Release notes

Version 2.0.3 - Bugfix

BUGFIX: Reference.cs assembly must only use keyword "new" if Microsoft.Bcl.AsyncInterfaces has been loaded. Which is kind of obvious in hindsight (issue #121)

Version 2.0.2 - API version update to 1.6.11 and support for Powershell 7.3.1+

NEW: Support for API version 1.6.11. New commands: Get-AtwsInventoryProduct, New-AtwsInventoryProduct, Remove-AtwsAccountAlert, Remove-AtwsInventoryProduct, Set-AtwsComanagedAssociation, Set-AtwsInventoryProduct (issue #120)
BUGFIX: Support for Powershell 7.3.1+. Big thank you to @TwiggyDev! (issue #119)
BUGFIX: Connect-AtwsWebAPI should work without parameters in Azure Funtions (issue #118)

Version 2.0.1 - API version update to 1.6.9

NEW: Support for API version 1.6.9. Affected commands: Get-AtwsAttachmentInfo, Get-AtwsBillingItem, Get-AtwsContractNote, Get-AtwsInvoiceTemplate, Get-AtwsTicketChecklistItem, New-AtwsContractNote, New-AtwsTicketChecklistItem, and Set-AtwsTicketChecklistItem.ps1

Version 2.0.0 - ArgumentCompleter release - disk cache no longer needed

NEW: Module finally supports automatic loading - just install module and run a command to automatically connect (if you do not have a saved profile yet you will be prompted for credentials interactively)
NEW: Support automatic connection on Azure Automation (runbooks) and Azure Functions without separate connection code
NEW: A fix for the 'SQL too nested' error has been found that cover most use cases
NEW: Conversion of datetime to/from local time is now configurable Set-AtwsModuleConfiguration -DateConversion (Disabled|Local|'specific/timezone')
NEW: UserDefinedFields can now be added to return object as separate properties or a hashtable (object.UDF) Set-AtwsModuleConfiguration -UdfExpansion (Disabled|Inline|Hashtable)
NEW: Properties with picklists can now have index values replaced with text labels or have text labels added as extra property Set-AtwsModuleConfiguration -PicklistExpansion (Disabled|Inline|LabelField)
NEW: Support for named configurations. You can save different credentials to disk (NB! Credentials are only encrypted using SecureString!)
NEW: Connect-AtwsWebApi can now run without parameters, provided you have saved a Default connection profile
UPDATE: New parameters for Connect-AtwsWebApi are AtwsModuleConfiguration, AtwsModuleConfigurationName and AtwsModuleConfigurationPath (with short aliases)
NEW: New function New-AtwsModuleConfiguration, required parameters are Credential and SecureTrackingIdentifier, ProfileName is optional (see Get-Help New-AtwsModuleConfiguration)
NEW: New function Get-AtwsModuleConfiguration, required parameter is Name (ProfileName)
NEW: New function Save-AtwsModuleConfiguration, required parameters are none (will save current credentials and settings to disk as Default profile)
NEW: New function Set-AtwsModuleConfiguration, required parameters are at least one (no point in running it if you don't want to change anything)
NEW: New function Remove-AtwsModuleConfiguration, required parameter is Name (ProfileName)
NEW: Errorlimit for bulk updates (default 10) has been exposed
NEW: Added function Build-AtwsModule as wrapper for complete refresh of module from API. Can be used when your tenant has received an API upgrade before I have access to the same API version to build an upgrade
NEW: Added custom mime mapping function Get-AtwsMindMapping. No access to system.web.mimemapping from powershell 7
NEW: New function Get-AtwsPicklistValue -Entity $entityName -FieldName $fieldName for easy access to picklist values and labels
UPDATE: Replaced [ValidateSet()] with [ArgumentCompleter()] for picklist! No longer any need for a personal cache on disk! Just install the module, connect and go!
DEPRECATED: There is no longer any need to cache files to disk to support intellisense for picklists. Removed code for personal disk cache.
REQUIREMENT: Moved minimum PowerShell requirement up from 4 to 5.
BUGFIX: Set-ATWSTask -UDF in conjunction with -NoDiskCache (issue #103) fixed
BUGFIX: All bugs found in RC2 have been squashed

Version 2.0.0-beta6 - Release candidate 2

UPDATE: Running Connect-AtwsWebApi without parameters or a saved profile will prompt for credentials and offer to save them
UPDATE: Better documentation for configuration profiles (Get-Help (New|Set|Save|Get)-AtwsModuleConfiguration)
UPDATE: Automatic quoting for PickLists from ArgumentCompleter sections
BUGFIX: A few more bugs was found and fixed

Version 2.0.0-beta5 - Release candidate 1

NEW: Module finally supports automatic loading - just install module and run a command to automatically connect (if you do not have a saved profile yet you will be prompted for credentials interactively)
NEW: Support automatic connection on Azure Automation (runbooks) and Azure Functions without separate connection code
NEW: A fix for the 'SQL too nested' error has been found that cover most use cases
NEW: Conversion of datetime to/from local time is now configurable Set-AtwsModuleConfiguration -DateConversion (Disabled|Local|'specific/timezone')
NEW: UserDefinedFields can now be added to return object as separate properties or a hashtable (object.UDF) Set-AtwsModuleConfiguration -UdfExpansion (Disabled|Inline|Hashtable)
NEW: Properties with picklists can now have index values replaced with text labels or have text labels added as extra property Set-AtwsModuleConfiguration -PicklistExpansion (Disabled|Inline|LabelField)
UPDATE: A lot of Pester tests have been added to make sure the new module version still work with old scripts and connection methods
UPDATE: Pester tests have been added to make sure new features work as advertised
UPDATE: Better errormessages with more details if you use -verbose
BUGFIX: Even more bugs have been located and squashed

Version 2.0.0-beta4

NEW: Support for named configurations. You can save different credentials to disk (NB! Credentials are only encrypted using SecureString!)
NEW: Connect-AtwsWebApi can now run without parameters, provided you have saved a Default connection profile
UPDATE: New parameters for Connect-AtwsWebApi are AtwsModuleConfiguration, AtwsModuleConfigurationName and AtwsModuleConfigurationPath (with short aliases)
NEW: New function New-AtwsModuleConfiguration, required parameters are Credential and SecureTrackingIdentifier, ProfileName is optional (see Get-Help New-AtwsModuleConfiguration)
NEW: New function Get-AtwsModuleConfiguration, required parameter is Name (ProfileName)
NEW: New function Save-AtwsModuleConfiguration, required parameters are none (will save current credentials and settings to disk as Default profile)
NEW: New function Set-AtwsModuleConfiguration, required parameters are at least one (no point in running it if you don't want to change anything)
NEW: New function Remove-AtwsModuleConfiguration, required parameter is Name (ProfileName)
NEW: Errorlimit for bulk updates (default 10) has been exposed
DEPRECATED: UserDefinedFields as hashtables has been axed. Broke Update().
UPDATE: New Pester test have been added
BUGFIX: Numerous bugs have been located and squashed

Version 2.0.0-beta3

BUGFIX: Fix for issue #94: Do not add timezone info to queries that uses a date, not a datetime value
BUGFIX: Fix for issue #93: ArgumentCompleter code parsed parentvalue field the wrong way (it should be looked up by index value,

Autotask

Install / Use

README