Using the New MOVEit 2018 REST API with PowerShell

Logging into MOVEit's console or web interface works great for day-to-day management tasks or setting up one-time workflows but there are times when we need to automate with MOVEit Automation!

Maybe you've got a simple process external to MOVEit that you'd like a MOVEit Automation task to be triggered from. Or perhaps MOVEit Automation is just one component in a much bigger orchestration of steps that you need accomplished. In either case, an API is critical to allow any product's features to be invoked remotely without the need for a GUI interface of any kind.

MOVEit  Automation has always had an API but it wasn't always the easiest to use. However, with MOVEit Automation 2018, we are able to use a modern REST API. A REST API allows us to interact with MOVEit Automation via HTTP. There are no dependencies on the client to speak of. This means that as long as we can write code in whatever language we prefer, we can use it to manipulate various things in MOVEit.

In this article, we're going to focus on using PowerShell with MOVEit's REST API. As you'll see in future articles, PowerShell isn't required to work with the API, but it is a popular choice among IT professionals wanting to write scripts with MOVEit Automation.

To understand how to use PowerShell to write scripts against MOVEit Automation, you first need to understand the PowerShell commands that make this all possible. These commands must be able to make HTTP requests with different verbs such as GET, POST, PUT, etc that MOVEit's API is built to understand.

PowerShell has two ways to send HTTP requests; they are Invoke-RestMethod and Invoke-WebRequest. Both send HTTP requests to the API the same way but Invoke-RestMethod has some extra capabilities like parsing any output a REST API returns. Both will work but if you're just getting your feet wet, it's probably a good idea to stick with Invoke-RestMethod. This command is the main command that will coordinate all activity to and from MOVEit's REST API. All of the other code is just preparing for the calls.

But enough about theory, let's get down to some code to see how this works!

First off, it's always a good idea to set some common attributes as variables at the top of your script and reference them throughout. To work with MOVEit's REST API, you'll first have to get an access token and use that access token to authenticate throughout your time working with the API. To get that access token, you must use the Authorization Token API. This API requires three attributes - a username, password and the method you'll be authenticating.

You may have noticed that I mentioned storing variables in the script, but then I said we'd need a password. We do need a password and we do need to reference it in the script but we don't have to store it in plain text. To get around this, we can store a PowerShell credential on disk once and then reference it as many times as we'd like.

First, save your MOVEit username and password to disk. You'll only have to do this once. This will not be in your script.

PS> Get-Credential | Export-CliXml -Path 'C:\MOVEitAutomationCred.xml'

Once you provide the username and password, both will be saved to disk. We now have a way to reference this via our script.

Next, let's start on the script. To get started, I'll first need to decrypt the username and password. Once I do this, I'll create a hashtable of attributes to store them in along with the other attributes I'll need.

PS> $cred = Import-CliXml -Path 'C:\MOVEitAutomationCred.xml'
 PS> $apiConfig = @{
 >>>    UserName = $cred.UserName
 >>>    Password = $cred.GetNetworkCredential().Password
 >>>    GrantType = 'password'
 >>>    MoveItHost = '<YourMOVEitAutomationServerNameHere>'
 >>> }

From the attributes in our hashtable, we can then infer all of the other components we need. First, I need to build the appropriate HTTP endpoint URL to get my access token.

PS> $authEndpointUrl = "https://$($apiConfig.MoveItHost)/webadmin/api/v1/token"
 PS> $authHttpBody = "grant_type=$($apiConfig.GrantType)&username=$($apiConfig.UserName)&password=$($apiConfig.Password)"

Once I have all of the attributes built, I can now make my first call to the MOVEit API to receive my access token. However, before I do that, I have to "trick" PowerShell to interact with my demo API since it's using a self-signed certificate.

Since Automation's API is SSL-encrypted with a certificate, it's necessary to use an HTTPS URL. However, in some instances (my demo environment), the certificate on my MOVEit Automation 2018 server is self-signed. This means my client (PowerShell) doesn't trust it. In a production environment, this will probably not be an issue. In any case, so I can demonstrate working with MOVEit's REST API, I have to use a .NET trick.

PS> [System.Net.ServicePointManager]::ServerCertificateValidationCallback = { $true }

Once I allow the use of a self-signed certificate, I can then make my first call to the authentication API to get my access token. You can see I'm using the HTTP POST method below to send a POST request to the endpoint.

PS> $token = Invoke-RestMethod  -Uri $authEndpointUrl -Method 'POST' -Body $authHttpBody
 PS> $token = $token.access_token

At this point, we have an access token and can call whatever APIs we desire. We just need to remember to always include the access token in all API calls or else it won't know who we are. This access token must be passed as an HTTP header. An easy way to ensure this is done is by creating a hashtable with the Headers parameter that Invoke-RestMethod will need and pass this to each reference using splatting.

PS> $authParam = @{
 >>>    Headers = @{ 'Authorization' = "Bearer $token" }
 >>> }

Now that we have the parameter built to pass to Invoke-RestMethod, as a demonstration, I'll just pull all of the tasks in MOVEit Automation. This API has a specific endpoint and HTTP method (like all APIs will) so I'll specify those with Invoke-RestMethod directly and assign the authorization parameter via splatting.

PS> $tasks = Invoke-RestMethod @authParam -Uri "https://$($apiConfig.MoveItHost)/webadmin/api/v1/tasks" -Method GET
 PS> $tasks
 paging                                                    sorting                                items
 ------                                                    -------                                -----
 @{page=1; perPage=2147483647; totalItems=3; totalPages=1} {@{sortField=Name; sortDirection=asc}} {@{Group=System.Object[]; I...

At this point, all of the tasks are stored in the items property. If you'd like to see the output in JSON, you could convert the objects to JSON using the ConvertTo-Json command.

PS> $tasks | ConvertTo-Json
 {
     "paging":  {
                    "page":  1,
                    "perPage":  2147483647,
                    "totalItems":  3,
                    "totalPages":  1
                },
     "sorting":  [
                     {
                         "sortField":  "Name",
                         "sortDirection":  "asc"
                     }
                 ],
     "items":  [
                   {
                       "Group":  "",
                       "ID":  "222223",
                       "Name":  "Tamper Check",
                       "Info":  "@{Description=\n\t\t\t\t; Notes=\n\t\t\t\t}",
                       "Parameters":  "",
                       "Schedules":  "@{Schedule=System.Object[]}",
                       "steps":  "",
                       "Active":  1,
                       "CacheNames":  "random",
                       "NextEID":  15
                   }
     ]
 }

What we've covered here is the basics of working with the MOVEit REST API. You must always get an access token and provide that token for every API call. In upcoming articles, we're going to cover some scenarios where this skill will come in handy.