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.

4 thoughts on “Automating with PowerShell: Using the new Autotask REST API

  1. Jeffrey Kosman

    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!

    Reply
    1. Jeffrey Kosman

      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.

      Reply
      1. Kelvin Tegelaar Post author

        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. ūüôā

        Reply
  2. Jeffrey Kosman

    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

    Reply

Leave a Reply

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.