Automating with PowerShell: Using the new Autotask REST API

So I’m a bit later than normal with blogging, that’s mostly because I was working on this project a little longer than usual. Autotask recently released update 2020.2 and this update includes a new REST API.

This is super cool, because the old API was a SOAP api and terribly inconvenient to actively use. To help people with using the new Autotask API I’ve created a module. The module is still in alpha/beta but you can download it from the PSGallery now.

The project page is here. Feel free to report any issues or do a pull request if you want to help develop the module! Just be prepared for breakage in the first couple of weeks, I’m still working on finding the best methods ūüôā

 Installation instructions

The module is published to the PSGallery, download it using:

   install-module AutotaskAPI

Usage

To¬†get¬†items¬†using¬†the¬†Autotask¬†API¬†you’ll¬†first¬†have¬†to¬†add¬†the¬†authentication¬†headers¬†using¬†the`¬†Add-AutotaskAPIAuth`¬†function.

$Creds = get-credential    Add-AutotaskAPIAuth -ApiIntegrationcode 'ABCDEFGH00100244MMEEE333 -credentials $Creds

When the command runs, You will be asked for credentials. Using these we will try to decide the correct webservices URL for your zone based on the email address. If this fails you must manually set the webservices URL.

Add-AutotaskBaseURI -BaseURI https://webservices1.autotask.net/atservicesrest

The Base URI value has tab completion to help you find the correct one easily.

To find resources using the API, execute the Get-autotaskAPIResource function. For the Get-AutotaskAPIResource function you will need either the ID of the resource you want to retrieve, or the JSON SearchQuery you want to execute. 

Examples


To find the company with ID 12345

Get-AutotaskAPIResource -Resource Companies -ID 12345

 To get all companies that are Active:

Get-AutotaskAPIResource -Resource Companies -SearchQuery "{filter='active -eq True'}"


To create a new company, we can either make the entire JSON body ourselves, or use the New-AutotaskBody function.

$Body = New-AutotaskBody -Definitions CompanyModel 


 This creates a body for the model Company. Definitions can be tab-completed. The body will contain all expected values. If you want an empty body instead use:

  $Body = New-AutotaskBody -Definitions CompanyModel -NoContent

After setting the values for the body you want, execute: New-AutotaskAPIResource -Resource Companies -Body $body

Contributions

Feel free to send pull requests or fill out issues when you encounter any.

6 Comments

  1. Jeffrey Kosman September 21, 2020 at 10:32 am

    Hi Kelvin,

    We want to read active directory for the number of active users. After that we want to upload the number to autotask. We created a UDF called ‘aantal gebruikers’ , but i’m strungling with selecting just that field.

    This is because the userDefinedFields contains multiple values.

    As an example:

    Get-AutotaskAPIResource -ID 186 -Resource Companies | Select-Object userDefinedFields

    results in:
    userDefinedFields
    ————————–
    {@{name=Aantal gebruikers; value=}, @{name=Kaseya Customer ID; value=}, @{name=Lead Source; value=}, @{name=Number of Employees; value=}…}

    I want to single out ‘Aantal gebruikers’ and add a value to it. How do i select that parameter?
    Thanks for all your great work!

    1. Jeffrey Kosman October 6, 2020 at 11:19 am

      I’ve gotten a bit further between projects. I have lots of files ready to be imported in the common fields (or UserDefinedFields) in the Autotask Customer portal.

      We have a hosting environment, and everyday I ‘collect’ the number of active directory users, mailbox usage, number of office licenses etc. All this data is saved in seperate files with the Autotask Company ID as name.

      For example: File “176” contains the number 48.30 which is the total mailbox usage in GB used by that particular customer.
      It works like a charm, but i really want to upload this information in the customer chart. So that we can report accurate information about different things at the same time.

      What i have now is:

      Get-AutotaskAPIResource -ID 267 -Resource Companies | Select-Object userDefinedFields | Convertto-Json
      which outputs in:

      {
      “userDefinedFields”: [
      {
      “name”: “Aantal gebruikers”,
      “value”: “0.0000”
      },
      {
      “name”: “Kaseya Customer ID”,
      “value”: null
      },
      {
      “name”: “Lead Source”,
      “value”: null
      },
      {
      “name”: “Number of Employees”,
      “value”: “11.0000”
      },
      {
      “name”: “Passportal Live Link company number”,
      “value”: null
      },
      {
      “name”: “projectnummer Kaseya”,
      “value”: “**”
      },
      {
      “name”: “Schijfruimte bijgekocht (in GB)”,
      “value”: null
      },
      {
      “name”: “Schijfruimte in gebruik Files (in GB)”,
      “value”: null
      },
      {
      “name”: “Schijfruimte in gebruik Mailboxen (in GB)”,
      “value”: null
      },
      {
      “name”: “Schijfruimte volgens Contract (in GB)”,
      “value”: null
      }
      ]
      }

      I want to be able to alter the value of “Aantal gebruikers” (number of users) from “0” to “10”
      Or the “schijfruimte” (diskspace) from “0” to “48.30”.

      But it don’t understand how to upload the new json file to autotask, so that this particular customer has ‘new data’.

      I tried something like this:
      $a = Get-AutotaskAPIResource -ID 267 -Resource Companies | Select-Object userDefinedFields | ConvertTo-Json
      $a.update | % {if($_.name -eq ‘Aantal gebruikers’){$_.value=10}}
      $a | ConvertFrom-Json | Set-AutotaskAPIResource -Resource Companies
      But it just gives the following output:

      itemId
      ——
      0

      I’ve searched and searched and only your API program looks to be the answer. I even tried using Invoke-Restmethod stuff, but i couldn’t make it work. And the internet only has answers for altering a json file in a folder on your computer.
      I’ve reached out to Autotask, but they don’t do any support for API’s and refer to the forums.

      Or is it just not possible to alter an UDF this way? Thanks for reading this. Hopefully you can point me in the right direction.

      1. Kelvin Tegelaar October 6, 2020 at 11:39 am

        Hi Jeffrey,

        This is more Powershell basics, I’d suggest to take a look at my PowerShell webinars to get a better grasp on this.

        To answer your first question; you’re trying to access a object property. You can do this by using the following example:
        (Get-AutotaskAPIResource -ID 186 -Resource Companies).userDefinedFields

        UserDefinedFields are a key-value hashtable. This means you can filter that with “Where object”
        (Get-AutotaskAPIResource -ID 186 -Resource Companies).userDefinedFields | where-object {$_.name -eq “Aantal Gebruikers”}.

        To change the “Aantal gebruikers” to ’10’ you can use the following code:

        Get-AutotaskAPIResource -ID 186 -Resource Companies | foreach-object { ($_.UserDefinedFields | where-object {$_.name -eq “Aantal Gebruikers”}).value = ’10’; $_} | Set-AutotaskAPIResource -Resource Companies

        This gets the company with ID 186. Changes the value of “Aantal gebruikers” to 10, returns the entire object and uploads it to the companies resource in Autotask. you don’t have to mess with json as the PowerShell module does that for you.

        Hope this helps. ūüôā

  2. Jeffrey Kosman October 7, 2020 at 7:25 am

    Hi Kelvin,

    Thanks a million, this made a real difference for us! I’ve learned a lot just from a single post ūüôā Looking forward to the webinars and more of your articles. Keep it up!

    kind regards

  3. Kyle Anderson February 10, 2021 at 7:09 pm

    this is fantastic i am starting at a new company soon that uses autotask and my first thought was, i really hope someone else built a module for integrating with auto task ūüôā that said I have used TFVC and am currently teaching myself GIT so once i get up to speed with that i can definitely work through helping with this project!

  4. Sean April 23, 2021 at 3:31 am

    Hi,

    This script is fantastic, I have it creating tickets and was wondering is it possible to add an attachment to a ticket when creating or update a ticket with an attachment?

    If it is possible, would you have an example on how to go about doing it?

    Cheers,
    Sean

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.