Woots PowerShell

Abstract

Op deze Github vind je een PowerShell module voor het interfacing met Woots Web API v2. Dit is gebaseerd op de Woots API documentatie. Op dit moment zijn 185 API aanroepen als functie geimplementeerd. Daarvan zijn 2 nog niet geimplementeerd.

Vereisten

Woots PowerShell module vereist PowerShell 5, PowerShell 7 of hoger.

Installatie

De module bestaat uit drie bestanden: Woots.psm1, Woots.psd1 en Woots-generatedcode.ps1.

1. Bepaal de PowerShell modulemap waar je de Woots module wilt toevoegen.

2. Maak hierin een submap Woots.

3. Download de bestanden Woots.psm1, Woots.psd1 en Woots-generatedcode.ps1 en plaats deze in een PowerShell modulemap.

Note	Een modulemap voor Windows PowerShell tot en met versie 5.1 is bijvoorbeeld C:\Users\username\Documents\WindowsPowerShell\Modules. Raadpleeg de environment variabele $ENV:PSModulePath om te zien waar de modulemappen op jouw computer staan.

Gebruik

Je kunt de module in je scripts gebruiken door de module te importeren als volgt.

Import-Module Woots

Initializeer Woots door een aanroep naar Initialize-Woots. Deze functie verwacht 3 parameters:

• $Hostname : Dit is de hostname deel van de Woots API endpoint URL. In geval van https://app.woots.nl/api/v2, dan is dit het deel "app.woots.nl".

• $School_id : Dit is een unieke nummer voor de schoolomgeving in Woots. De school_id is zichtbaar in de Wootsportal onder Mijn account > API-token.

• $Token : Dit is een hexadecimale string van 30 tekens waarmee toegang tot de Woots API wordt geauthoriseerd. Je kunt deze aanmaken in de Wootsportal onder Mijn account > API-token.

Documentatie

Werp een blik op de functiedefinities in Woots-generatedCode.ps1 om te zien welke functies er allemaal gedefinieerd zijn.

Functieparameters

Alle functies slechts één of meer van de volgende parameters.

• $Id : het numeriek ID van de resource waarop de bewerking betrekking heeft (alle functies van de categorie Get-Resource, Get-ResourceItem, Set-Resource, Add-ResourceItem, Remove-Resource).

• $Parameter : een hastable met de in te stellen attributen van een resource (alle functies van de categorie Add-Resource, Add-ResourceItem, Set-Resource, Set-ResourceItem), of een hashtable met naam-waarde-paren die het filter definieren voor een zoekactie (alle functies van de categorie Search-Resource).

• $MaxItems : een getal , dat indien groter dan 0, het hoogste aantal items aangeeft, dat moeten worden opgehaald. Bij weglating van deze parameter of bij een negatieve waarde, wordt het maximum aantal beschikbare items geretourneerd (alle functies van de categorie Search-Resource, Get-AllResources).

Alle parameters zijn PowerShell objecten, behalve waar het gaat om booleaanse waarden; in dat geval volstaat de string "false" of "true".

Voorbeeld:

$filter = @{
    name = "Aardrijkskunde"
    trashed = "false"
}
$result = Search-WootsCourse -Parameter $filter

Functieretourwaarden

Alle functies retourneren wat er wordt opgehaald via de API aanvraag.

Extra’s

Een deel van de code in de module is gegenereerd door een codegenerator.

• WootsModuleCodeGenerator.ps1 : dit script genereert de code in Woots-generatedcode.ps1.

• Woots-api-calls.csv : dit bestand wordt ingelezen door WootsModuleCodeGenerator.ps1.

Changes

• 20230802 : added "charset=utf-8" to contenttype of Invoke-WebRequest to be able to send special chars in names and such.

WootsModuleCodeGenerator.ps1

• 20230815 Extract api calls automatically from https://stage.woots.nl/api/docs/v2/swagger.yaml

• 20230815 Added generation date and openapi version umber in generated code

• 20230815 added API call for logs

• 20230815 output code sorted and grouped by category