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
If you receive the message "Install-Package: Administrator rights are required to install or update. Log on to the computer with an account that has Administrator rights, and then try again, or install by adding "-Scope CurrentUser" to your command. You can also try running the Windows PowerShell session with elevated rights (Run as Administrator)." despite running in an elevated session, then the cause might be Windows controlled folder access.
To resolve this go to:
  1. 1.
    Windows Security settings / Virus & threat protection / Virus & threat protection settings / Manage settings / Manage controlled folder access
  2. 2.
    Disable Controlled folder access
  3. 3.
    Install the package
  4. 4.
    Re-enable Controlled folder access

Using the package

Pre-requisites

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.
Don't forget to save the App - your credentials won't work until the app has been saved.

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.
If your Trelica instance is hosted in the EU, then you should call:
Initialize-TrelicaCredentials -BaseUrl https://eu.trelica.com
If you want to store the credentials file somewhere else, then use the -StorePath parameter.
You can delete the credentials file using the -Delete switch.
Automatic encryption using Windows user account credentials is not supported on Linux. Read more about Microsoft's PowerShell SecretManagement module if you're running on Linux or want more flexibility about safely storing API credentials.

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, for any reason, you need to re-enter your Client Id and Secret, just call Initialize-TrelicaCredentials with the -Reset switch.
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:
SecretManagement and SecretStore are Generally Available
PowerShell Team
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.[email protected].com Steven Porrit
rachel.[email protected].com Rachel Schindler
jay.[email protected].com Jay Garcia
If you're running PowerShell scripts unattended then you will need to find a secure way to unlock your store. There's a good Stack Exchange article on safely using passwords in scripts on Linux.
Copy link
Outline
Installing the PowerShell package
Using the package
Pre-requisites
Getting started
Using credentials to get a Trelica Context object
Making an API request
Common tasks
Convert API output to JSON
Select data
Pass a filter
Loop through data
Set credentials for a service account
Using Microsoft's SecretManagement module