Calling from PowerShell

PowerShell is a powerful cross-platform scripting language.

We recommend using the Trelica PowerShell package which is published in the PowerShell Gallery.

Have a look at the Trelica Github repository for some sample scripts.

Installing the PowerShell package

PowerShell packages can be installed for just the current user or all users.

If you are wanting to use the package with a scheduled task for example, you may be running the task in a different user account, so you will need to install for all users.

Installing for all users requires elevated rights, so you will need to run a PowerShell session as an Administrator.

To install for the current user, run:

Install-Module -Name Trelica -Scope CurrentUser

To install for all users, run:

Install-Module -Name Trelica -Scope AllUsers

Using the package

Prerequisites

The PowerShell module assumes that you have created an OAuth2 Client App in Trelica using the Client credentials flow.

If you do this you will have generated a Client ID and a Client Secret.

Getting started

You could simply paste your Client ID and Client Secret into your PowerShell script as strings. This is a really bad idea - for example scripts sometimes get checked-in to public repositories or are shared with other people.

The Trelica API package uses the Windows Data Protection API (DPAPI) to encrypt and store your API Client Secrets in a file. These are encrypted using your current Windows user account's login credentials, and so the file can only be decrypted when you are logged in with the same Windows user account.

To get started, enter:

Initialize-TrelicaCredentials

The first time you run this, you will be prompted to enter your Client ID and Secret at the User and Password prompts respectively:

Credentials path: C:\Users\Me\Trelica
PowerShell credential request
Please enter your Trelica API Client ID and Secret when prompted for User and Password respectively
User: UaQD5J21ARhKjQyFTYokxkieXqM9SM9RaUMHxQBIPjD
Password for user UaQD5J21ARhKjQyFTYokxkieXqM9SM9RaUMHxQBIPjD: ***

credential                                baseUrl
----------                                -------
System.Management.Automation.PSCredential https://app.trelica.com

Your credentials will now be saved in a JSON file in a folder called Trelica under your user account's "home" path.

Initialize-TrelicaCredentials -BaseUrl https://eu.trelica.com

If you want to load or store the credentials file somewhere else, then use the -StorePath parameter. e.g. to create credentials in a different folder, you would use:

Initialize-TrelicaCredentials -StorePath /Users/batch/trelicaCreds

You can delete the credentials file using the -Delete switch.

Using credentials to get a Trelica Context object

The next time you run Initialize-TrelicaCredentials it will read the stored credentials without you having to re-enter them.

You can now use the credentials to generate an access token for making API calls. Simply pass the results of Initialize-TrelicaCredentials to the Get-TrelicaContext function:

$context = Initialize-TrelicaCredentials | Get-TrelicaContext

This will return a Trelica Context object, which is essentially just a token and a baseUrl.

If you're using Microsoft's PowerShell SecretManagement module then you can get use the Get-TrelicaCredentials command to create a Trelica Context object from a stored secret (in this example called 'TrelicaAPI'):

$context = (Get-Secret -Name TrelicaAPI) `
    | Get-TrelicaCredentials | Get-TrelicaContext

Making an API request

To make an API request you can call Invoke-TrelicaRequest.

This takes a context either passed through the pipeline or with the -Context parameter.

$context | Invoke-TrelicaRequest -Path "/api/workflows/v1"

Common tasks

Convert API output to JSON

API requests are returned as PowerShell objects. To convert to JSON just pass the output to ConvertTo-Json:

Invoke-TrelicaRequest -Context $context `
    -Path "/api/workflows/v1" | ConvertTo-Json -Depth 4

Select data

Initialize-TrelicaCredentials | Get-TrelicaContext `
    | Invoke-TrelicaRequest -Path "/api/workflows/v1" `
    | Select -ExpandProperty results | Select Id, Name

Pass a filter

You can pass additional items in the query string using the -QueryStringParams parameter

$qs = @{ filter = 'steps[status eq "Waiting"]' }
$runs = Invoke-TrelicaRequest -Context $context `
    -Path "/api/workflows/v1/$id/runs?limit=50" `
    -QueryStringParams $qs

Loop through data

Trelica API endpoints return a "next" object if there are additional pages of data to process (apart from Users which adheres to the SCIM protocol).

This makes it simple to request multiple pages of data:

$path = "/api/workflows/v1/$id/runs?limit=50"
do {
    $runs = Invoke-TrelicaRequest -Context $context -Path $path
    $path = $runs.next
    # do something 
} while ($path)

Set credentials for a service account

If you are running a non-interactive scheduled job from a service account you will need to enter the credentials before the scheduled task runs.

To do this, you should first run Initialize-TrelicaCredentials from a PowerShell session using the service account.

First find Powershell and open the folder where the short-cut is stored:

Click Open file location. Now hold down Shift and right-click the short-cut icon:

You will then be prompted to login with new credentials.

Now you can run Initialize-TrelicaCredentials (or Initialize-TrelicaCredentials -Reset if you already set them and want to reset) to set and store the correct Client ID and Secret.

Using Microsoft's SecretManagement module

If you're using Linux or want more flexibility about where you store API secrets for use in PowerShell we strongly recommend using Microsoft's SecretManagement module.

This is a great introductory article:

https://devblogs.microsoft.com/powershell/secretmanagement-and-secretstore-are-generally-available

The SecretManagement module lets you plug-in different secret stores or vaults (including Azure KeyVault). There's a simple disk-based vault that you can use out of the box called SecretStore.

To get started, just install the relevant modules:

Install-Module Microsoft.PowerShell.SecretManagement, Microsoft.PowerShell.SecretStore

Now create a test vault:

Register-SecretVault -Name SecretStore `
    -ModuleName Microsoft.PowerShell.SecretStore -DefaultVault

Prompt yourself to enter some credentials, and store them in the vault using the name TrelicaAPI.

$credential = Get-Credential -Message "Please enter your Client ID and Secret when prompted for User and Password respectively"
Set-Secret -Name TrelicaAPI -Secret $credential

These can be retrieved and turned into an access token, in this case for an organization hosted in Trelica's EU cloud:

$context = (Get-Secret -Name TrelicaAPI) | `
    Get-TrelicaCredentials -BaseUrl https://eu.trelica.com | `
    Get-TrelicaContext

Armed with a context, you can now invoke API calls and process results:

(($context | Invoke-TrelicaRequest -Path "/api/scim/v2/Users").Resources) | `
    Select userName, displayName

userName                                displayName
--------                                -----------
steven.porrit@trelica.com               Steven Porrit
rachel.schindler@trelica.com            Rachel Schindler
jay.garcia@trelica.com                  Jay Garcia