varnamo-kommun/istadminapi

Powershell module for integrations against EduCloud

Table of Contents

• Table of Contents
• About The Project
  • Built With
• Getting Started
  • Prerequisites
  • Installation
• Changelog
• Usage
• Roadmap
• Acknowledgements

About The Project

Coming from IST Extens, transitioning to IST Administration has brought us a lot of new and exciting possibilities. Having access to all of our data through EduCloud has given us the ability to control the flow of things much better. In light of DNP (Digitala nationella prov) we saw the potential of the EduCloud API and that's when this project was born.

Built With

• Powershell
• VSCode
• EduCloud

Getting Started

First, we're happy that you are here! Hopefully you will find some use for this module in your organisation. There are a few steps you will need to complete before you can use this module. Please make sure you've followed each one.

Prerequisites

• Powershell 5.1
• API key to EduCloud to get access to the API.

Installation

1. Clone the repo or download it directly from here.

git clone https://github.com/VMO-IT-avdelningen/ISTAdminAPI.git

2. Upon first import of the module, you will only have access to the following cmdlets:

• New-Secret
• Get-Secret
• Initialize-SettingsFile

3. Start by creating a credential file: New-Secret -Name <Name of the file> -Path <Path to store the secret> -Username <The API service account username> You will be prompted to enter the password for the service account. Note that the credential file will only be readable by the account thats creates it, and on the very same machine. So if you are going to automate things with the module, be sure to generate the credential file with the appropriate service account.

4. Open an elevated powershell prompt. This is because when configuring the module the first time, a .checkfile containing the location of the settings file will be created under $env:ProgramData. Run Initialize-SettingsFile and provide it with your CustomerId eg. SE00100 A popup window will appear asking you to select a folder to store your settings. The settings will be stored in .CSV format. Another popup window will appear asking you to locate your credential file. This will be the file that you previously created with the New-Secret Cmdlet.

5. Import the module again, this time with the -Force parameter to ensure the module loads your settings.

6. See each Cmdlet help section for further usage.

Changelog

ISTAdminAPI is currently only maintained by one person. I will try to add as many features as possible.

• Version 0.0.1.2 - 2024-04-19
  • Added documentation for all the public cmdlets. Find them under /Docs
  • Rewritten a few steps when constructing the request url.
  • Clean up of Initialize-SettingsFile
  • New cmdlet:
    • Get-ISTGroup - Retrieve your groups
    • Parameters:
      • [string[]]GroupType
      • [string[]]SchoolType
      • [guid[]]Parent
      • [guid]Id
      • [guid[]]LookUp
      • [switch]ExpandAssignmentRole
      • [string]StartDateOnOrBefore
      • [string]StartDateOnOrAfter
      • [string]EndDateOnOrBefore
      • [string]EndDateOnOrAfter
• Version 0.0.1.1 - 2024-04-15
  • Repository made public
  • New cmdlet:
    • Get-ISTOrganisation - Retrieve your organisations
    • Parameters:
      • [string[]]OrgType
      • [string[]]SchoolType
      • [guid]Id
      • [guid[]]Parent
      • [guid[]]LookUp_Ids
      • [string[]]LookUp_SchoolUnitCodes
      • [string[]]LookUp_OrganisationCodes
• Version 0.0.1.0 - 2024-04-02
  • First commit.
  • Available public cmdlets:
    • Get-ISTPerson - Retrieve users/persons from the EduCloud API.
    • Parameters:
      • [string]NameContains
      • [string]CivicNo
      • [guid]Id
      • [string]RelationshipEntity
      • [guid]RelationshipOrganisation
      • [guid[]]LookUp
      • [string]LookUpType
      • [string]ExpandProperties
      • [string]StartDateOnOrBefore
      • [string]StartDateOnOrAfter
      • [string]EndDateOnOrBefore
      • [string]EndDateOnOrAfter
    • Get-ISTDuty - Retrieve one or multiple duties connected to an organisation.
    • Parameters:
      • [guid]Organisation
      • [string]DutyRole
      • [guid]PersonId
      • [guid]Id
      • [guid[]]LookUp
      • [switch]ExpandPerson
      • [string]StartDateOnOrBefore
      • [string]StartDateOnOrAfter
      • [string]EndDateOnOrBefore
      • [string]EndDateOnOrAfter

Usage

Take a look at the documentation under /Docs. There are plenty of examples to help you get started.

You can also utilize the powershell help function like this:

Get-Help -Name Get-ISTOrganisation -Full

Roadmap

• Adding compability for handling programmes
• Adding compability for handling studyplans
• Adding compability for handling syllabuses
• Adding compability for handling groups (2024-04-19 - v.0.0.1.2)

Acknowledgements

IST team for the very well documented API EduCloud